@zvndev/darkmown 1.3.0 → 1.5.0

package/AGENTS.md

@@ -253,6 +253,8 @@ input:focus-visible
 ```
 Always include: a tokens block, a real type scale, generous spacing, a `max-width` centered `main`, styled `button`/`input` with `:hover`/`:focus-visible` states, and a responsive `@media` rule (`.skin` supports `@media` — its indented rules are wrapped automatically). The `font` property is the CSS shorthand when it leads with a size (`font 16px/1.6 system-ui`) and `font-family` otherwise. Prefer `.skin`; a plain `<style>` block in a `.wd` also works.
 
+**Scoped styles — opt in with `scoped`.** A `.skin` is **global** by default (style site-wide; the right default for your design system). To stop a reusable component's classes from clashing with the rest of the page, make the **first line** of its `.skin` the word `scoped` — its selectors then only match the component it's colocated with (a page skin scopes that page; an include skin scopes just that include's subtree). You still write `class="card"`; the build stamps a `data-wd-scope` attribute and rewrites the selectors — zero runtime, a static page stays static. **Tokens stay global** (a `tokens`/`tokens dark` block still emits `:root` vars, so `$accent` and dark mode keep working). Escape a single rule with `:global(.x)` (whole-selector only). `page`/`*`/`html`/`body`/`::selection` are a compile error in a scoped skin — those belong in a global skin.
+
 **Layout gotcha — CTAs and link rows.** Markdown wraps adjacent links/buttons on consecutive lines into a single `<p>`, so putting `display:flex` on their container won't space them. To lay out a row of buttons or nav links, wrap them in explicit raw HTML and style that:
 ```wd
 <div class="actions">

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 1.5.0 — 2026-06-28
+
+Content collections — query a folder of markdown as data, with optional typed validation and pagination. Plus a default-styling pass so buttons and form controls look good out of the box, and two fixes from a product review. The runtime is unchanged (still 7459 B gzipped); collections and styling are entirely build-time.
+
+- **Content collections.** Any `site/pages/<name>/` subdirectory is a queryable collection, referenced by its **bare name** in the existing loop — no new concept, no config file. `@loop blog into post sort by date desc paginate 10` reads the entries under `site/pages/blog/`, each as a row of its frontmatter plus derived `url`, `slug`, and `excerpt`. The whole `where` / `sort` / format-pipe / `:if` machinery works unchanged, and a pure listing stays zero-JS (`runtime: false`). Drafts are excluded by default (and can never leak into a listing); `build --drafts` includes them.
+- **Typed schemas (optional).** Drop a `_schema.wd` at a collection's root to validate every entry's frontmatter at build time — one `field: type` per line over a closed vocabulary (`string`, `number`, `boolean`, `date`, `string[]`, trailing `?` = optional). Mismatches fail the build with a `file:line` error naming the entry and field. Absent `_schema.wd` = no validation (opt-in, like everything else).
+- **Pagination.** `paginate N` on a collection loop multiplies one listing source into static pages — page 1 stays at `/blog/`, the rest at `/blog/page/2/`, `/blog/page/3/`. A `{ page.current }` / `{ page.total }` / `{ page.prev }` / `{ page.next }` pager is available in the listing scope; every generated page is static HTML in `routes.json` + `sitemap.xml`.
+- **Polished default styling.** `:button`/`:submit` compile to a bare classless `<button>`, so their look came entirely from the base skin — which previously left them as flat/unstyled. The base skin and **all five scaffold templates** now ship a token-driven default for buttons (filled-accent with hover/active/focus-visible/disabled states, plus `.secondary`/`.ghost` variants) and form controls (inputs, selects with a custom chevron, textareas, checkbox/radio/range) — consistent in light **and** dark, with `prefers-reduced-motion` honored. A freshly scaffolded site looks good immediately.
+- **Fixes (from a product review).** (1) Scoped-style stamping no longer corrupts the contents of raw-text elements (`<script>`/`<style>`/`<textarea>`/`<title>`) — it stamps their opening tags but leaves their bodies byte-intact. (2) Nested static routes (e.g. `/blog/<slug>/`, `/blog/page/2/`) now correctly receive the strict (no `unsafe-eval`) CSP on Vercel; the header drift-guard now validates full route paths so the gap can't recur.
+
+## 1.4.0 — 2026-06-28
+
+Scoped styles — the long-standing "`.skin` selectors are global" gap, closed. Opt-in, compile-time, and **zero runtime** (the shared runtime is still 7459 B gzipped; nothing new ships to the client but one HTML attribute and one attribute selector).
+
+- **`scoped` skins.** Put `scoped` as the first line of a `.skin` file and its selectors apply only to the page or include it ships with — so two components can reuse the same class name (`.card`) without colliding. The compiler appends a per-file `[data-wd-scope="wd-xxxx"]` attribute to each selector's subject and stamps the matching subtree's HTML; the scope id is a stable hash of the skin's path. Selectors compose as you'd expect: descendant selectors scope only the subject, comma lists scope each branch, `@media`/`@supports` wrappers pass through, and `&`-nesting/pseudo-classes resolve before the attribute is attached.
+- **Tokens stay global.** A `tokens` / `tokens dark` block in a `scoped` skin still emits global `:root` custom properties, so `var(--…)`, dark mode, `:theme`, and the `$code-*` highlight tokens keep working across the whole site — only your component's selector rules are scoped.
+- **`:global(...)` escape hatch** for a whole selector that must stay global (e.g. a class you portal elsewhere). Page-level selectors (`page`, `*`, `html`, `body`, `::selection`) are rejected in a scoped skin with a corrective hint — those belong in a global design-system skin.
+- **Fully backward compatible.** A `.skin` without the `scoped` marker is unchanged, byte-for-byte (covered by a golden test). Existing global skins — `base.skin`, `nav.skin`, every scaffolded project — keep styling the whole site exactly as before. Unused scoped selectors produce a build *warning* (never silently removed, since a colocated `.js` behavior may add the class at runtime).
+
 ## 1.3.0 — 2026-06-28
 
 The "table-stakes batteries" release — the build-time, zero-JS features a markdown site is expected to ship. The runtime is unchanged (still 7459 B gzipped, well under the 8 KB budget); everything here is compile-time HTML/CSS or build output.

package/README.md

@@ -113,7 +113,7 @@ tags: [sales, revenue, "q1, q2"]
 
 Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card).
 
-A few reserved keys drive **drafts and feeds** (see [SEO & feeds](#seo--feeds-sitemap-rss-robots) below): `draft: true` excludes a page from production builds; `site_url` on the home page turns on `sitemap.xml` + `rss.xml`; `date:` marks a page as a blog post (it lands in `rss.xml` and sets the page's `<lastmod>`); `excerpt:` is the RSS summary.
+A few reserved keys drive **drafts and feeds** (see [SEO & feeds](#seo--feeds-sitemap-rss-robots) below): `draft: true` excludes a page from production builds; `site_url` on the home page turns on `sitemap.xml` + `rss.xml`; `date:` marks a page as a blog post (it lands in `rss.xml` and sets the page's `<lastmod>`); `excerpt:` is the RSS summary. The same frontmatter is queryable when the page is an entry in a [content collection](#content-collections) — `{ post.date }`, `{ post.excerpt }`, `{ post.tags }`, and any custom key resolve in an `@loop` over the folder.
 
 `transitions: true` opts a page into **instant, flash-free navigation** — zero JavaScript, all declarative. It emits a directional fade+slide **view transition** for the page swap (old lifts up and out, new rises up and in — replacing the default cross-fade, which left both pages ghosted at ~50 % opacity mid-navigation), plus a **`<script type="speculationrules">` prerender** hint that renders the next same-origin page on hover/pointerdown so the click activates an already-painted page (no white render-gap flash). It honors `prefers-reduced-motion`. Only same-origin pages that both opt in transition; browsers without support — or with page-preloading disabled — navigate normally. Off by default; opt out with `transitions: false`. Mark a link `{.no-prefetch}` to exclude it from prerendering. (Chrome disables prerendering while DevTools is open, so test the built site with DevTools closed.)
 
@@ -351,6 +351,75 @@ That is a full add-to-cart / remove-line flow — and a to-do list with delete
 >
 > **Per-row actions inside an inner loop:** `cart += member` (append-row) works from an inner loop — it carries the inner item into a top-level `:state`/`:store` list. But a per-row **`remove`** needs a top-level list as its source, and an inner loop's source is a path off the outer row (`team.members`), so deleting an inner row in place is **not** supported — the compiler rejects it with a corrective message. Carry the row into a top-level list and remove it there.
 
+## Content collections
+
+**Any folder under `site/pages/` is a queryable collection** — referenced in `@loop` by its bare name. There is no `content/` root to opt into and no marker file to add: a `site/pages/blog/` directory of posts *is* the `blog` collection.
+
+```wd
+@loop blog into post sort by post.date desc
+- [{ post.title }]({ post.url }) — { post.date }
+@endloop
+```
+
+It's the same one loop, with the same clauses (`where`, `sort by`, `reverse`, `offset`, `limit`, format pipes). The collection resolves at **build time**, so a pure listing ships **zero JavaScript** (`runtime: false`).
+
+Each entry's frontmatter becomes a row, plus three fields the framework derives:
+
+| Field | Value |
+|---|---|
+| `{ post.url }` | the entry's route, e.g. `/blog/hello/` |
+| `{ post.slug }` | the filename without extension (an `index.md` uses its folder name) |
+| `{ post.excerpt }` | the frontmatter `excerpt:`, else the first paragraph of a `.md` body |
+
+Scalar frontmatter is coerced for querying, so `where post.featured == true` and numeric sorts behave like they do over a JSON file. **Drafts never leak:** a `draft: true` entry is excluded from a default build's listing (included only under `darkmown build --drafts`), exactly like routing and feeds.
+
+### Typed schema — `_schema.wd`
+
+Drop a `_schema.wd` at a collection's root to validate every entry's frontmatter at build time. It's frontmatter-shaped — one `field: type` rule per line:
+
+```wd
+---
+title: string
+date: date
+description: string
+excerpt: string?
+tags: string[]?
+---
+```
+
+The vocabulary is small and closed: `string`, `number`, `boolean`, `date`, `string[]`, each with a trailing `?` to mark it optional. A missing required field, a wrong type, an unknown extra field (a typo guard), or an unknown type token in the schema itself each **fail the build** with a `file:line` and the offending field. Validation is **opt-in** — no `_schema.wd`, no validation.
+
+### Pagination — `paginate N`
+
+Add `paginate N` (collections only) to split a listing into static pages: **page 1 keeps the listing's own route**, and pages 2+ live at `/<route>/page/2/`, `/<route>/page/3/`, … Every generated page is static HTML and appears in `routes.json` and `sitemap.xml`.
+
+```wd
+@loop blog into post sort by post.date desc paginate 5
+- [{ post.title }]({ post.url })
+@endloop
+
+Page { page.current } of { page.total }
+:if page.prev
+[← Newer]({ page.prev })
+:endif
+:if page.next
+[Older →]({ page.next })
+:endif
+```
+
+A `page` pager is exposed to the whole page:
+
+| Variable | Value |
+|---|---|
+| `{ page.current }` | 1-based current page number |
+| `{ page.total }` | total number of pages |
+| `{ page.prev }` | URL of the previous page, or `""` on page 1 |
+| `{ page.next }` | URL of the next page, or `""` on the last page |
+
+The pager is plain `<a href>` links to the generated routes — **zero JavaScript**. `paginate` is for collections only (route-multiplication only makes sense for a folder of entries) and can't combine with `offset`/`limit` (it owns the slice).
+
+> See the [live blog demo](https://darkmown.com/blog/) — the whole index, paginated and sorted, is one `@loop` over `site/pages/blog/`, validated by a `_schema.wd`, shipping no framework JS.
+
 ## Sections
 
 ```wd
@@ -809,6 +878,50 @@ A single `tokens dark` block powers **both** theming paths: it compiles to `:roo
 
 Because `tokens dark` already emits the `[data-theme="dark"]` rule, **no extra skin block is needed** — the same palette drives the toggle. `"light"` forces the light palette even under OS dark; `"auto"` clears the attribute and follows the OS again; `theme` persists across reloads and tabs like any `:store`. (`:theme name = "light"` renames the store and seeds a different default. The older `tokens [data-theme=dark]` block — a manual-only override — still works for bespoke setups.)
 
+## Scoped styles — `scoped`
+
+*New in 1.4.0.* By default a colocated `.skin` is **global** — its selectors match the whole page, exactly like a stylesheet. That's the right default for a design system. But when two components both want a class called `.card`, global CSS makes them fight. Opt a skin into **scoping** so its selectors only ever match the component it ships with: make the **first line** of the `.skin` file the word `scoped`.
+
+```skin
+scoped
+
+.card
+  padding 1.5rem
+  bg $panel
+  radius $radius
+```
+
+Scoping is **pure compile time** — a short, path-derived id (e.g. `wd-7c21`) is stamped onto the component's HTML (`data-wd-scope="wd-7c21"`) and appended to each of the skin's selectors:
+
+```css
+.card[data-wd-scope="wd-7c21"] { padding: 1.5rem; }
+.card[data-wd-scope="wd-7c21"] { background: var(--panel); }
+```
+
+A second component's `.card` gets a **different** id, so the two never collide. There is **no runtime cost and no class renaming in your markup** — you still write `class="card"`; the framework adds the attribute during the build. A static page with a scoped skin stays **zero-JS**.
+
+**What scopes, what stays global:**
+
+| In a `scoped` skin | Result |
+|---|---|
+| A selector rule (`.card`, `.card:hover`, `.card .title`, `h2, h3`) | Scoped — the attribute lands on the **subject** (rightmost) selector, before any `:hover`/`::before` so it stays valid CSS |
+| A descendant selector (`.card .title`) | Only `.title` (the subject) is scoped; `.card` matches inside the subtree |
+| `tokens` / `tokens dark` / `tokens [data-theme=…]` | **Global** — design tokens always emit on `:root`, so `$accent` and dark mode keep working site-wide |
+| `:global(.toast)` (whole selector) | **Opts back out** — emits a plain, unscoped `.toast { … }` |
+| `@media` / `@supports` wrappers | Untouched; only the inner rule's selector is scoped |
+| `page` / `*` / `html` / `body` / `::selection` | **Compile error** — page-level styles belong in a global skin, not a scoped one |
+
+Where the scope applies depends on **where the skin lives**:
+
+- A skin colocated with a **page** (`about.skin` next to `about.wd`) scopes that page's body.
+- A skin colocated with an **include** (`card.skin` next to `card.wd`) scopes just that include's subtree wherever it's `@include`d — so the same scoped component can appear many times on a page without leaking into its neighbours.
+
+**Caveats (honest limits this release):**
+
+- **Whole-selector `:global()` only.** A descendant `:global` (`.card :global(.x)`) is **not** supported yet — use a whole-selector `:global(.x)`.
+- **Unused selectors warn, they aren't removed.** If a scoped selector's class/element/id never appears in the stamped subtree, the build prints `hint: scoped selector ".badge" in card.skin matches no element` — but the rule is **kept** (a colocated `.js` may add the class at runtime). It's a typo nudge, not a dead-code remover.
+- **Scoping is opt-in.** Every existing `.skin` (no `scoped` marker) is byte-for-byte unchanged.
+
 ## The escape hatch
 
 Reactive pages expose `window.wd` so a colocated `.js` file can do anything the directives deliberately don't — keyboard, drag/touch, canvas, charts, maps:

package/docs/spec-alignment.md

@@ -134,6 +134,36 @@ Four progressive-disclosure capabilities plus an assets and a security change. T
 - **Page-colocated static assets:** any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and colocated `.skin`/`.js`) is copied to `dist/` at its path (`site/pages/logo.svg` → `dist/logo.svg`). The shelf (`site/_/` → `/__wd/media`, `/__wd/data`) is unchanged; a name clash with an emitted route is skipped with a warning. As of v0.14.1, hidden path segments (`.`, `-`, `_`) and symlinked page assets are skipped. `.avif` was added to the served content-types.
 - **`:fetch` URL scheme hardening (security):** `:fetch`/`refresh=` URLs are validated at compile time — relative, `http(s)://`, or a leading `{ state }` interpolation are allowed; protocol-relative `//host` and non-http(s) schemes (`file:`, `data:`, `javascript:`, …) are rejected with a corrective hint. **This is scheme validation, not a host allowlist** — SSRF to arbitrary http(s) hosts remains the author's responsibility (see the trust boundary).
 
+## 1.5.0 additions — typed content collections + pagination (2026-06-29)
+
+The 1.5.0 cycle ships the headline **content collections** feature: turning a folder of pages into a queryable, typed, paginated data source — entirely at build time. **Zero runtime impact** — it is build-time glue over the existing `@loop` pipeline; `src/runtime.js` and the 8 KB budget are untouched, and a pure collection listing stays `runtime: false`.
+
+- **Zero-ceremony collections — bare folder name as `@loop` source.** ANY `site/pages/<name>/` subdirectory is a collection, referenced by its **bare name** (`@loop blog into post`). There is no `content/` root and no marker file; an existing `site/pages/blog/` becomes a collection with zero file moves. A build-time **collection index** (`src/compiler/collections.js`, `buildCollections`) is assembled from the router's already-parsed `route.meta` — frontmatter is **never re-parsed** — and threaded into the compilation as `comp.collections` (added to `context.js`). **Row shape:** every frontmatter field plus three derived fields — `url` (the entry route), `slug` (filename stem; an `index.*` entry uses its folder name), and `excerpt` (frontmatter `excerpt:` → first paragraph of a `.md` body via `feeds.js`'s `firstParagraph`; `.wd` bodies are not scanned). The derived keys are added **after** the frontmatter spread so a stray `url:`/`slug:` can't shadow real route data. Scalar frontmatter is **coerced** (`true`/`false` → boolean, numeric strings → number) **only** in the collection row (never in the global frontmatter parser), so `where post.featured == true` and numeric sorts behave like they do over a JSON file. **The same one loop** — `where`/`sort by`/`reverse`/`offset`/`limit`/format-pipes/`:if`/`:every` all work unchanged because a collection resolves to the same array of rows; a bare-name resolution sits **after** `:state` (a declared `:state` of the same name still wins) and a `where` that reads `:state` still makes the loop reactive (baked rows). An unresolved bare source errors with a `file:line` + the list of available collection names.
+
+- **Drafts never leak into a default-build listing.** Collection rows are built from the **post-draft-filter** route list (the same `discoverRoutes` chokepoint routing/feeds use), so a `draft: true` entry is excluded from a default build's listing and included only under `darkmown build --drafts` — regression-tested on both paths.
+
+- **Optional typed schema — `_schema.wd`.** A `_schema.wd` at a collection root opts the collection into build-time validation (absent = no validation, like `scoped`/`draft`). The DSL is **frontmatter-shaped** — one `field: type` rule per line inside the `---` block — written exactly like the frontmatter it validates. The type vocabulary is **small and closed**: `string`, `number`, `boolean`, `date`, `string[]`, each with a trailing `?` for optional. Validation throws on the first violation with a `file:line` and the offending field: a missing required field, a wrong type, or an **unknown extra field** (a typo guard — `titel:` is caught) all fail the build; framework-recognized keys (`url`/`slug`/`excerpt`/`draft`) are allowed implicitly. An **unknown type token in the schema itself** is a compile error pointing at the schema `file:line`.
+
+- **Pagination — `@loop … paginate N`.** A new clause (collections only) multiplies the listing into static pages: **page 1 keeps the listing's own clean route**, pages 2+ live at `/<route>/page/<n>/`. The compiler records the pagination intent (`comp.pagination`, post-`where`/`sort` page count) during a discovery compile; `src/builder.js` then recompiles each page with the correct `page` pager seeded into the document scope and emits every generated route into `routes.json` + `sitemap.xml` (RSS is dated-posts-only, unaffected). The **pager** exposed to the template scope is `{ page.current }` / `{ page.total }` (numbers) and `{ page.prev }` / `{ page.next }` (URLs, empty string at the ends) — plain `<a href>` links to the generated routes, **zero JS**. `paginate` is a positive-integer literal, rejects a non-collection source (route-multiplication only makes sense for a folder of entries), and can't combine with `offset`/`limit` (it owns the slice) or `sortable`.
+
+- **Demo (four-file rule):** the existing `site/pages/blog/` became a real collection — `blog/index.wd` is one paginated `@loop` over the folder (sorted date-desc, `paginate 3`, linking each entry by `{ post.url }`, with a styled `index.skin` and a `{ page.* }` pager), validated by `blog/_schema.wd`, across five genuine dated posts (so `/blog/` + `/blog/page/2/` both emit) plus a draft that proves exclusion. RSS/sitemap keep working over the collection. Tests in `tests/collections.test.js` (resolution, row shape incl. url/slug/excerpt, where/sort, draft exclusion + `--drafts` inclusion, schema pass+fail with `file:line`, pagination route-multiplication + pager vars + `/blog/page/2/` shape, `runtime: false` on a pure listing, every `paginate` guard). **Honest caveats:** `paginate N` is a build-time route split only — no client-side pagination; pagination is collections-only (a JSON-file/`:state` source is rejected); tag/taxonomy pages and image optimization are deferred to 1.6.0.
+
+## 1.4.0 additions — compile-time scoped styles (2026-06-28)
+
+The 1.4.0 cycle ships one feature: **opt-in scoped styles** for colocated `.skin` files, closing the "no CSS scoping" gap an audit flagged (two components couldn't reuse a class name without collision). **Pure compile time, zero runtime** — `src/runtime.js` and the 8 KB budget are untouched, and a static page with a scoped skin stays `runtime: false`.
+
+- **Authoring surface — the `scoped` marker:** a `.skin` scopes its selectors **only** when its first non-comment, non-blank, non-divider line is exactly `scoped`; colocation alone changes nothing. Every existing `.skin` (no marker) stays **global** and emits **byte-identical CSS** to before (golden-tested against `site/_/base.skin`). `scoped` anywhere but the first line is a compile error (`"scoped" must be the first line of a .skin file`). The only other new surface is `:global()` inside a scoped skin — no new `.wd` syntax.
+
+- **Mechanism — id + selector rewrite + HTML stamp.** The scope id is a short, deterministic hash of the skin's **project-relative path** (e.g. `wd-7c21`) — path-based (stable across content edits, unique per file), computed in `src/builder.js` (the coordination point) and re-derived identically by the HTML stamp from the same path, so `src/skin.js` stays a pure string→CSS function (`compileSkin(src, { scope })`). In scoped mode `compileSkin` appends `[data-wd-scope="<id>"]` to the **subject** (rightmost compound) of each comma-separated selector, **after** `&`-nesting resolves and **before** any trailing pseudo-class/element (`.card[data-wd-scope="…"]:hover`, never `.card:hover[…]`; `::before` likewise) — so descendant selectors scope only the subject (`.card .title` → `.title` gets the attribute) and `@media`/`@supports` wrappers are untouched. The HTML half (`stampScope` in `src/compiler/page.js`, an `enhanceImages`-style regex post-pass) stamps `data-wd-scope="<id>"` onto every opening tag of the scoped subtree that doesn't already carry one (first stamp wins, so a nested include keeps its own id). A **page**-colocated scoped skin stamps the page body; an **include**-colocated scoped skin is stamped in `handleInclude` over just that include's returned subtree — so the same scoped component repeats on a page without its scope leaking to siblings.
+
+- **Tokens stay global.** A `tokens` / `tokens dark` / `tokens [attr]` block in a scoped skin still emits a global `:root { --name: … }` (and the dark/manual-toggle variants) — never scoped — so `var(--x)`, dark mode, `:theme`, and the `$code-*` highlight tokens keep resolving site-wide. Enforced by only touching the selector-rule construction, leaving the token/`:root` path identical.
+
+- **`:global()` escape + disallowed selectors.** A **whole-selector** `:global(.toast)` emits a plain, unscoped `.toast { … }`. Page-level selectors in a scoped skin — `page` (→ body), bare top-level `*`/`html`/`body`/`::selection`, and any bare top-level declaration that would land on `:root` — are a **compile error** with a hint pointing to a global skin (chosen over silently auto-`:global`-ing them).
+
+- **Unused-selector handling — warn, never remove.** The builder has both the scoped subject set (collected by `compileSkin`) and the stamped subtree HTML, so it warns (`hint: scoped selector ".badge" in card.skin matches no element`) when a scoped subject's class/element/id never appears in the stamped subtree — but **keeps the rule** (a colocated `.js` may add the class at runtime). A typo nudge, not a dead-code remover.
+
+- **Honest caveats:** only **whole-selector** `:global()` this release — descendant `:global` (`.card :global(.x)`) is deferred; unused selectors **warn, are not removed**. Demonstrated end-to-end by the [`/scoped/`](/scoped/) demo (two components reuse `.card` with no collision; a global skin still works alongside).
+
 ## 1.3.0 additions — table-stakes batteries (2026-06-28)
 
 The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Tracks land in parallel; this entry covers the **syntax-highlighting** and **drafts + feeds** tracks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/_/base.skin

@@ -37,6 +37,13 @@ tokens
   radius 12px
   radius-sm 8px
   radius-lg 20px
+  field-bg #ffffff
+  field-line #d9d2c4
+  field-line-strong #c4baa8
+  control-shadow 0 1px 2px rgba(28,24,20,.06)
+  control-shadow-hover 0 6px 18px -8px rgba(28,24,20,.45)
+  accent-press #094339
+  on-accent #ffffff
 
 tokens dark
   ink #ece6db
@@ -66,6 +73,13 @@ tokens dark
   code-number #f2bb8a
   code-punctuation #b6c2bc
   ring #5ccab4
+  field-bg #1a1612
+  field-line #38301f
+  field-line-strong #4a3f2c
+  control-shadow 0 1px 2px rgba(0,0,0,.4)
+  control-shadow-hover 0 8px 22px -10px rgba(0,0,0,.7)
+  accent-press #b6ecdc
+  on-accent #0c1310
 
 /* ── Reset & base ───────────────────────────────────────────────── */
 
@@ -156,45 +170,234 @@ main
   color $accent
   margin 0 0 .35rem
 
-/* ── Buttons ────────────────────────────────────────────────────── */
-
-.btn
+/* ── Buttons ────────────────────────────────────────────────────────
+   Two ways to get a button, ONE consistent look:
+   1. The `.btn` class (for link-styled buttons: <a class="btn">).
+   2. A bare <button> — what the `:button`/`:submit` directives emit with
+      no class. Both share the same sizing, states, and tokens so a demo,
+      a scaffold, or a docs page looks designed without per-page styling.
+   The bare-button default is the ACCENT (filled) treatment, because a
+   directive button is almost always the page's primary action. Opt down
+   to a quieter look with class="secondary" / class="ghost".
+   ─────────────────────────────────────────────────────────────────── */
+
+/* Shared geometry + motion for every button-shaped thing. One-line comma
+   selector (multi-line comma lists silently drop all but the last). */
+.btn, button, button[data-wd-action], button[data-wd-actions], [type=submit], [type=button], [type=reset]
   display inline-flex
   align-items center
+  justify-content center
   gap .5rem
   margin .4rem .5rem .4rem 0
-  padding .7rem 1.15rem
-  font-size .95rem
-  font-weight 550
-  line-height 1
+  padding .62rem 1.15rem
+  font-family system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+  font-size .94rem
+  font-weight 560
+  line-height 1.15
+  letter-spacing -.005em
   color $ink
   bg $panel
   border 1px solid $line
   radius 999px
   text-decoration none
   cursor pointer
-  transition transform .12s ease, box-shadow .12s ease, background .12s ease
-
-.btn:hover
-  transform translateY(-1px)
-  box-shadow 0 6px 18px -8px rgba(28,24,20,.35)
+  -webkit-appearance none
+  appearance none
+  transition transform .14s cubic-bezier(.2,.7,.3,1), box-shadow .14s ease, background .14s ease, border-color .14s ease, color .14s ease
 
-.btn.primary
+/* The filled accent default — applies to bare directive buttons and to
+   the opt-in `.btn.primary` / `.btn.warm` link variants. One-line list. */
+button, button[data-wd-action], button[data-wd-actions], [type=submit], .btn.primary
   bg $accent
-  color #fff
+  color $on-accent
   border-color $accent
+  box-shadow $control-shadow
 
-.btn.primary:hover
+button:hover, button[data-wd-action]:hover, button[data-wd-actions]:hover, [type=submit]:hover, .btn.primary:hover
   bg $accent-deep
-  color #fff
+  border-color $accent-deep
+  color $on-accent
+  transform translateY(-1px)
+  box-shadow $control-shadow-hover
+
+button:active, button[data-wd-action]:active, button[data-wd-actions]:active, [type=submit]:active, .btn.primary:active
+  bg $accent-press
+  border-color $accent-press
+  transform translateY(0)
+  box-shadow $control-shadow
+
+/* Visible keyboard focus on every interactive control — accessibility. */
+.btn:focus-visible, button:focus-visible, [type=submit]:focus-visible, [type=button]:focus-visible, [type=reset]:focus-visible
+  outline 2px solid $ring
+  outline-offset 2px
+
+button:disabled, [type=submit]:disabled, .btn[aria-disabled=true], [type=button]:disabled
+  opacity .5
+  cursor not-allowed
+  box-shadow none
+  transform none
+
+/* Quieter, neutral button — a secondary/cancel action. One-line list. */
+.btn, button.secondary, button.ghost, .btn.secondary, .btn.ghost
+  bg $panel
+  color $ink
+  border-color $line
+
+.btn:hover
+  transform translateY(-1px)
+  box-shadow $control-shadow-hover
+
+button.secondary:hover, .btn.secondary:hover
+  bg $sunk
+  border-color $line
+  color $ink
+  transform translateY(-1px)
+  box-shadow $control-shadow-hover
+
+button.ghost, .btn.ghost
+  bg transparent
+  border-color transparent
+  box-shadow none
+
+button.ghost:hover, .btn.ghost:hover
+  bg $sunk
+  box-shadow none
+  transform none
 
 .btn.warm
   bg $warm
   color #fff
   border-color $warm
 
-.btn.ghost
-  bg transparent
+.btn.warm:hover
+  bg $warm
+  color #fff
+
+/* ── Form controls ──────────────────────────────────────────────────
+   `:input`/`:bind`/`:textarea`/`:select` emit bare <input>/<textarea>/
+   <select> — style them here so forms look designed by default. ─────── */
+
+input, textarea, select
+  font-family system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+  font-size .95rem
+  line-height 1.4
+  color $ink
+  bg $field-bg
+  border 1px solid $field-line
+  radius $radius-sm
+  padding .58rem .8rem
+  margin .35rem 0
+  width 100%
+  max-width 28rem
+  -webkit-appearance none
+  appearance none
+  transition border-color .14s ease, box-shadow .14s ease, background .14s ease
+
+input::placeholder, textarea::placeholder
+  color $faint
+
+input:hover, textarea:hover, select:hover
+  border-color $field-line-strong
+
+input:focus-visible, textarea:focus-visible, select:focus-visible
+  outline none
+  border-color $accent
+  box-shadow 0 0 0 3px $accent-soft
+
+input:disabled, textarea:disabled, select:disabled
+  opacity .55
+  cursor not-allowed
+  bg $sunk
+
+textarea
+  min-height 6.5rem
+  resize vertical
+
+/* Native select chevron (the appearance reset hides the default arrow). */
+select
+  background-image url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 24 24' fill='none' stroke='%23756a5d' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E")
+  background-repeat no-repeat
+  background-position right .75rem center
+  padding-right 2.25rem
+  cursor pointer
+
+/* Checkbox / radio — accent-tinted, comfortable hit target. The directive
+   emits <label><input type=checkbox|radio> Text</label> in .wd-checkboxes /
+   .wd-radios groups. One-line comma list. */
+.wd-checkboxes, .wd-radios
+  display flex
+  flex-direction column
+  gap .55rem
+  margin .5rem 0
+
+.wd-checkboxes label, .wd-radios label
+  display flex
+  align-items center
+  gap .55rem
+  cursor pointer
+
+[type=checkbox], [type=radio]
+  width 1.1rem
+  height 1.1rem
+  min-width 1.1rem
+  margin 0
+  max-width none
+  padding 0
+  accent-color $accent
+  cursor pointer
+
+[type=checkbox]:focus-visible, [type=radio]:focus-visible
+  outline 2px solid $ring
+  outline-offset 2px
+
+label
+  font-size .95rem
+  color $ink-soft
+
+/* The range slider (`:slider`) — tint the track to the brand accent. */
+[type=range]
+  accent-color $accent
+  cursor pointer
+  padding 0
+
+/* Framework control buttons (`:carousel` injects these at runtime). They
+   must NOT inherit the big accent pill above — reset them to a compact,
+   neutral round control. Page skins can still override. One-line lists. */
+.wd-carousel-prev, .wd-carousel-next
+  width 2.25rem
+  height 2.25rem
+  padding 0
+  margin 0
+  bg $panel
+  color $ink
+  border 1px solid $line
+  radius 999px
+  box-shadow $control-shadow
+
+.wd-carousel-prev:hover, .wd-carousel-next:hover
+  bg $panel
+  border-color $accent
+  color $accent
+  transform none
+  box-shadow $control-shadow-hover
+
+.wd-carousel-dot
+  width .6rem
+  height .6rem
+  padding 0
+  margin 0
+  border 0
+  radius 999px
+  bg $line
+  box-shadow none
+
+.wd-carousel-dot:hover
+  bg $faint
+  transform none
+  box-shadow none
+
+.wd-carousel-dot[aria-current=true]
+  bg $accent
 
 /* ── Cards & surfaces ───────────────────────────────────────────── */
 
@@ -359,6 +562,16 @@ blockquote
   margin 0
   radius 0
 
+/* ── Motion preference ──────────────────────────────────────────────
+   Honour users who ask for less motion: drop the button lift/transition.
+   (@media must be indented in a .skin — its rules wrap automatically.) ── */
+
+@media (prefers-reduced-motion: reduce)
+  .btn, button, [type=submit], [type=button], input, textarea, select
+    transition none
+  .btn:hover, button:hover, [type=submit]:hover
+    transform none
+
 /* ── Footer ─────────────────────────────────────────────────────── */
 
 .sitefooter

package/site/_/nav.wd

@@ -2,10 +2,10 @@
   <a class="brand" href="/">Darkmown</a>
   <span class="nav-links">
     <a href="/docs/">Docs</a>
+    <a href="/blog/">Blog</a>
     <a href="/showcase/">Showcase</a>
     <a href="/reactive/">Reactive</a>
     <a href="/data/">Data</a>
-    <a href="/highlight/">Highlight</a>
   </span>
   <a class="nav-gh" href="https://github.com/ZVN-DEV/darkmown">GitHub ↗</a>
 </nav>

package/site/_/scoped-promo.skin

@@ -0,0 +1,43 @@
+scoped
+
+/* Component A — a warm promo card. Same class names as scoped-stat.skin
+   (.card / .title / .body), but scoped, so neither leaks. Tokens stay global,
+   so $accent / $warm / $radius still resolve from base.skin's :root. */
+
+.card
+  display grid
+  gap .6rem
+  padding 1.5rem
+  bg $warm-soft
+  border 1px solid $warm
+  border-left 4px solid $warm
+  radius $radius
+
+.badge
+  justify-self start
+  font-size .7rem
+  font-weight 700
+  text-transform uppercase
+  letter-spacing .08em
+  color #fff
+  bg $warm
+  padding .2rem .55rem
+  radius 999px
+
+.title
+  margin 0
+  font-size 1.25rem
+  color $ink
+
+.body
+  margin 0
+  color $ink-soft
+  max-width none
+
+.cta
+  justify-self start
+  font-weight 600
+  color $warm
+
+.cta:hover
+  color $ink

package/site/_/scoped-promo.wd

@@ -0,0 +1,10 @@
+<!-- Scoped component A. Its colocated scoped-promo.skin opts into scoping, so the
+     `.card` here gets its OWN look — a warm, accent-bordered promo — without
+     clashing with the identically-named `.card` in scoped-stat.wd. handleInclude
+     stamps just this returned subtree with the component's scope id. -->
+<article class="card">
+  <span class="badge">Promo</span>
+  <h3 class="title">Same class name, zero collision</h3>
+  <p class="body">This <code>.card</code> is a warm promo panel. The component beside it also calls its root <code>.card</code> — and they do not fight, because each scoped skin only matches inside its own stamped subtree.</p>
+  <a class="cta" href="/docs/">How scoping works →</a>
+</article>

package/site/_/scoped-stat.skin

@@ -0,0 +1,32 @@
+scoped
+
+/* Component B — a dark stat tile. Identical class names to scoped-promo.skin,
+   but a completely different look. Scoping keeps them apart; tokens are global
+   so $accent-deep / $accent / $radius-lg come straight from base.skin's :root. */
+
+.card
+  display grid
+  gap .35rem
+  justify-items center
+  text-align center
+  padding 2rem 1.5rem
+  bg $accent-deep
+  border 1px solid $accent-deep
+  radius $radius-lg
+
+.title
+  font-size 3rem
+  font-weight 700
+  line-height 1
+  color #fff
+
+.body
+  margin 0
+  max-width none
+  color $accent-soft
+
+.badge
+  font-size .68rem
+  text-transform uppercase
+  letter-spacing .1em
+  color $accent

package/site/_/scoped-stat.wd

@@ -0,0 +1,9 @@
+<!-- Scoped component B. Reuses the SAME class names as scoped-promo.wd
+     (.card / .title / .body) but its colocated scoped-stat.skin scopes them to a
+     dark, centered stat tile. Proof the leak is gone: two `.card` definitions on
+     one page, each only styling its own subtree. -->
+<article class="card">
+  <span class="title">99.9%</span>
+  <p class="body">uptime, because there is no client framework to crash</p>
+  <span class="badge">measured</span>
+</article>