@zvndev/darkmown 1.3.0 → 1.5.0

package/site/pages/reactive.skin

@@ -29,18 +29,44 @@ h2
   padding-top 1.2rem
 
 button
-  border 1px solid $ink
-  bg $ink
+  display inline-flex
+  align-items center
+  justify-content center
+  gap .5rem
+  border 1px solid $accent
+  bg $accent
   color white
-  padding .72rem 1rem
+  padding .6rem 1.1rem
   margin .3rem .5rem .3rem 0
-  radius $radius
-  font inherit
+  radius 999px
+  font system-ui, -apple-system, "Segoe UI", Roboto, sans-serif
+  font-size .92rem
+  font-weight 560
+  line-height 1.15
   cursor pointer
+  appearance none
+  box-shadow 0 1px 2px rgba(23,23,23,.08)
+  transition transform .14s cubic-bezier(.2,.7,.3,1), box-shadow .14s ease, background .14s ease, border-color .14s ease
 
 button:hover
   bg $accent
   border-color $accent
+  transform translateY(-1px)
+  box-shadow 0 8px 18px -8px rgba(22,100,90,.5)
+
+button:active
+  transform translateY(0)
+  box-shadow 0 1px 2px rgba(23,23,23,.08)
+
+button:focus-visible
+  outline 2px solid $accent
+  outline-offset 2px
+
+button:disabled
+  opacity .5
+  cursor not-allowed
+  box-shadow none
+  transform none
 
 a
   color $accent
@@ -89,4 +115,10 @@ ul
   bg transparent
   color $warm
   border 1px solid $line
-  padding .35rem .8rem
+  padding .4rem .9rem
+  box-shadow none
+
+.card.line button:hover
+  bg $warm
+  border-color $warm
+  color white

package/site/pages/scoped/index.skin

@@ -0,0 +1,23 @@
+scoped
+
+/* Page-scoped skin for this route. The whole page body is stamped, so these
+   selectors style only this page's own markup — proving page-level scoping
+   alongside the two include-scoped components. A :global() escape hatch shows a
+   single rule opting back out to a plain, unscoped selector. */
+
+.intro
+  margin 2rem 0 3rem
+
+.duo
+  margin 3rem 0
+
+.how
+  margin 4rem 0 2rem
+
+.how ul
+  color $ink-soft
+
+/* :global escape — this selector ships UNSCOPED, matching site-wide. */
+:global(.scoped-note)
+  font-size .85rem
+  color $muted

package/site/pages/scoped/index.wd

@@ -0,0 +1,47 @@
+---
+title: Scoped styles — same class name, zero collision
+description: Two components reuse the class name .card and never clash. Compile-time scoped styles stamp each component's subtree with a path-derived id and rewrite its skin's selectors to match only there. Zero runtime JS — a static page stays static.
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 1.4</span>
+
+# Scoped styles
+
+Two components on this page both call their root element `.card`. In plain CSS the second skin would overwrite the first. Here they coexist: a `.skin` whose first line is `scoped` only ever styles the subtree it ships with. It's pure compile time — a path-derived id stamped onto the HTML and appended to the skin's selectors. No runtime, no class hashing in your markup, no collision.
+
+</section>
+
+<section class="duo">
+
+<div class="grid cols-2">
+
+@include /scoped-promo.wd
+@include /scoped-stat.wd
+
+</div>
+
+</section>
+
+<section class="how">
+
+## What actually shipped
+
+- The `.card` in the warm promo and the `.card` in the dark stat tile are **different rules**, scoped to different ids.
+- This page also uses a **global** skin (`base.skin`, via `/base.wd`) — `.btn`, `.eyebrow`, `.grid` still work everywhere, unscoped.
+- Design **tokens stay global**: every scoped skin still reads `$accent`, `$warm`, `$radius` from `:root`, so dark mode keeps working for free.
+- A `:global(.x)` selector inside a scoped skin opts a single rule back out.
+
+<a class="btn primary" href="/docs/">Read the docs</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/site/pages/store.skin

@@ -32,28 +32,65 @@ a
   color $accent
 
 button
-  border 1px solid $ink
-  bg $ink
+  display inline-flex
+  align-items center
+  justify-content center
+  gap .5rem
+  border 1px solid $accent
+  bg $accent
   color white
-  padding .72rem 1rem
+  padding .6rem 1.1rem
   margin .3rem .5rem .3rem 0
-  radius $radius
-  font inherit
+  radius 999px
+  font system-ui, -apple-system, "Segoe UI", Roboto, sans-serif
+  font-size .92rem
+  font-weight 560
+  line-height 1.15
   cursor pointer
+  appearance none
+  box-shadow 0 1px 2px rgba(23,23,23,.08)
+  transition transform .14s cubic-bezier(.2,.7,.3,1), box-shadow .14s ease, background .14s ease, border-color .14s ease
 
 button:hover
   bg $accent
   border-color $accent
+  transform translateY(-1px)
+  box-shadow 0 8px 18px -8px rgba(22,100,90,.5)
+
+button:active
+  transform translateY(0)
+  box-shadow 0 1px 2px rgba(23,23,23,.08)
+
+button:focus-visible
+  outline 2px solid $accent
+  outline-offset 2px
+
+button:disabled
+  opacity .5
+  cursor not-allowed
+  box-shadow none
+  transform none
 
 input
-  padding .7rem .9rem
+  padding .62rem .85rem
   border 1px solid $line
   radius $radius
   font inherit
+  font-size .95rem
   bg $panel
   width 100%
   max-width 360px
   margin 1rem 0
+  appearance none
+  transition border-color .14s ease, box-shadow .14s ease
+
+input:hover
+  border-color $accent
+
+input:focus-visible
+  outline none
+  border-color $accent
+  box-shadow 0 0 0 3px rgba(22,100,90,.18)
 
 #shop
   border 1px solid $line

package/src/builder.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverApiRoutes } from "./api-runner.js";
+import { buildCollections } from "./compiler/collections.js";
 import { compilePage, parseFrontmatter } from "./compiler.js";
 import { createPaths } from "./config.js";
 import {
@@ -17,7 +18,7 @@ import {
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
 import { HIGHLIGHT_CSS } from "./highlight.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
-import { compileSkin } from "./skin.js";
+import { compileSkin, scopeIdFor } from "./skin.js";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
@@ -59,6 +60,12 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
   const routes = discoverRoutes(paths.routesRoot, { includeDrafts: options.includeDrafts });
+  // Build the collection index from the (post-draft-filter) routes — every
+  // site/pages/<name>/ subdirectory's entries become queryable rows a bare-name
+  // `@loop blog into post` resolves against. Drafts are already excluded, so a
+  // draft entry can never appear in a listing. Validates each collection's
+  // `_schema.wd` here (throwing on a bad entry with file:line).
+  const collections = buildCollections(routes, paths);
   // Site identity lives in the HOME page frontmatter (no config loader): the
   // `site_url` origin triggers + prefixes the feeds, reusing `title`/`description`
   // as the RSS channel fields. Resolved once, up front, so every page can link
@@ -80,35 +87,46 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   /** @type {string | undefined} HTML of the `/404/` route, copied to dist/404.html. */
   let notFoundHtml;
 
+  // Extra (paginated 2+) routes the build generates beyond the discovered set —
+  // each is indexable static HTML, so it belongs in the sitemap (it has no own
+  // frontmatter `date:`; it reuses its listing source file for `<lastmod>`).
+  /** @type {Route[]} */
+  const extraRoutes = [];
+
   for (const route of routes) {
-    const page = compilePage(route.file, paths, { feed: feedLink });
-    for (const warning of page.warnings || []) {
-      if (warned.has(warning)) continue;
-      warned.add(warning);
-      console.warn(`hint: ${warning}`);
-    }
-    const outFile = outputPathForRoute(paths.distRoot, route.route);
-    fs.mkdirSync(path.dirname(outFile), { recursive: true });
-    fs.writeFileSync(outFile, page.html);
-    if (route.route === "/404/") notFoundHtml = page.html;
-    emitAssets(page.assets, paths);
-    if (page.assets.runtime) emitRuntime(paths);
-    emitBehaviors(page.assets, paths);
-    if (page.assets.hasCode) emitHighlight(paths);
-    const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
-    manifest.push({
-      route: route.route,
-      file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
-      assets: {
-        skins: [...page.assets.skins],
-        scripts: [
-          ...(page.assets.runtime ? ["/__wd/runtime.js"] : []),
-          ...behaviorSrcs,
-          ...page.assets.scripts
-        ],
-        runtime: page.assets.runtime
+    // Compile each route's page(s). A normal route yields one page; a route whose
+    // `@loop … paginate N` slices a collection yields page 1 at the route plus
+    // `/<route>/page/<n>/` for pages 2..N — every one static HTML.
+    for (const page of compileRoutePages(route, paths, collections, feedLink)) {
+      if (page.route !== route.route) extraRoutes.push({ ...route, route: page.route });
+      for (const warning of page.warnings || []) {
+        if (warned.has(warning)) continue;
+        warned.add(warning);
+        console.warn(`hint: ${warning}`);
       }
-    });
+      const outFile = outputPathForRoute(paths.distRoot, page.route);
+      fs.mkdirSync(path.dirname(outFile), { recursive: true });
+      fs.writeFileSync(outFile, page.html);
+      if (page.route === "/404/") notFoundHtml = page.html;
+      emitAssets(page.assets, paths, page.html, warned);
+      if (page.assets.runtime) emitRuntime(paths);
+      emitBehaviors(page.assets, paths);
+      if (page.assets.hasCode) emitHighlight(paths);
+      const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
+      manifest.push({
+        route: page.route,
+        file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
+        assets: {
+          skins: [...page.assets.skins],
+          scripts: [
+            ...(page.assets.runtime ? ["/__wd/runtime.js"] : []),
+            ...behaviorSrcs,
+            ...page.assets.scripts
+          ],
+          runtime: page.assets.runtime
+        }
+      });
+    }
   }
 
   // Hosts (Vercel, Cloudflare Pages) and the framework's own server auto-serve
@@ -126,8 +144,10 @@ export function buildSite(cwd = process.cwd(), options = {}) {
 
   // Crawler files + feeds. robots.txt is ALWAYS emitted; sitemap.xml + rss.xml
   // need the home `site_url` (else a loud, actionable build hint). Drafts are
-  // already filtered out of `routes`, so neither feed can ever see one.
-  const feeds = emitFeeds(routes, identity, paths);
+  // already filtered out of `routes`, so neither feed can ever see one. The
+  // paginated 2+ routes are indexable HTML too, so they join the sitemap (RSS is
+  // dated-posts-only, which they are not, so it's unaffected).
+  const feeds = emitFeeds([...routes, ...extraRoutes], identity, paths);
 
   // Page-colocated static assets (images, SVG, fonts, …) copy last, so the guard
   // sees every emitted route/framework file already on disk.
@@ -146,6 +166,94 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   return { routes: manifest, distRoot: paths.distRoot, feeds };
 }
 
+/**
+ * A compiled page bound for a concrete output route. Mirrors `CompiledPage` plus
+ * the public `route` it's written to — for a paginated listing, page 1 keeps the
+ * listing route and pages 2+ get `/<route>/page/<n>/`.
+ * @typedef {object} EmittedPage
+ * @property {string} route Public route path this page is written to.
+ * @property {string} html
+ * @property {import("./compiler.js").Assets} assets
+ * @property {string[]} warnings
+ */
+
+/**
+ * Compile a route into the one-or-more static pages it emits. A normal route is
+ * one page. A route whose body paginates a collection (`@loop … paginate N`) is
+ * compiled once to discover the page count, then recompiled per page with the
+ * correct `page` pager seeded into scope — page 1 at the route, pages 2..total at
+ * `/<route>/page/<n>/`. Every emitted page is static HTML (`runtime: false` for a
+ * pure listing).
+ * @param {Route} route
+ * @param {Paths} paths
+ * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} collections
+ * @param {{ href: string, title: string } | undefined} feedLink
+ * @returns {EmittedPage[]}
+ */
+function compileRoutePages(route, paths, collections, feedLink) {
+  // First compile (discovery): page 1 with a placeholder pager. If the page has
+  // no `paginate`, this is the only compile and we emit it as-is.
+  const first = compilePage(route.file, paths, {
+    feed: feedLink,
+    collections,
+    vars: { page: pagerVars(route.route, 1, 1) }
+  });
+  if (!first.pagination || first.pagination.total <= 1) {
+    return [
+      { route: route.route, html: first.html, assets: first.assets, warnings: first.warnings }
+    ];
+  }
+  // Paginated: recompile every page (including page 1, whose pager `total`/`next`
+  // were unknown on the discovery pass) with the correct pager.
+  const total = first.pagination.total;
+  /** @type {EmittedPage[]} */
+  const pages = [];
+  for (let n = 1; n <= total; n++) {
+    const page = compilePage(route.file, paths, {
+      feed: feedLink,
+      collections,
+      vars: { page: pagerVars(route.route, n, total) }
+    });
+    pages.push({
+      route: pageRoute(route.route, n),
+      html: page.html,
+      assets: page.assets,
+      warnings: page.warnings
+    });
+  }
+  return pages;
+}
+
+/**
+ * The output route for page `n` of a paginated listing: page 1 keeps the
+ * listing's own clean route; pages 2+ live at `/<route>/page/<n>/`.
+ * @param {string} baseRoute Listing route (trailing-slashed).
+ * @param {number} n 1-based page number.
+ * @returns {string}
+ */
+function pageRoute(baseRoute, n) {
+  return n === 1 ? baseRoute : `${baseRoute}page/${n}/`;
+}
+
+/**
+ * Build the `{ page.* }` pager exposed to the template scope of a paginated
+ * listing: `current`/`total` numbers and `prev`/`next` URLs (empty string at the
+ * ends, so `{ page.prev }` renders nothing on page 1). Plain links to the
+ * generated routes — zero JS.
+ * @param {string} baseRoute Listing route.
+ * @param {number} current 1-based current page.
+ * @param {number} total Total page count.
+ * @returns {{ current: number, total: number, prev: string, next: string }}
+ */
+function pagerVars(baseRoute, current, total) {
+  return {
+    current,
+    total,
+    prev: current > 1 ? pageRoute(baseRoute, current - 1) : "",
+    next: current < total ? pageRoute(baseRoute, current + 1) : ""
+  };
+}
+
 /**
  * Resolve the site's identity from the HOME route's frontmatter — the single
  * place site-wide metadata lives this cycle (no config loader). `site_url` is
@@ -544,22 +652,95 @@ function emitHighlight(paths) {
 }
 
 /**
+ * Emit a page's colocated assets. `.skin` files compile through {@link compileSkin}
+ * (other files copy verbatim). A skin that opted into scoping (`assets.scopedSkins`)
+ * compiles in scoped mode: the scope id is derived here from its PROJECT-RELATIVE
+ * PATH — the single coordination point with the HTML stamp, which derives the same
+ * id from the same path — and threaded into `compileSkin({ scope })`. The compiler
+ * also reports the scoped subject selectors, which we check against the stamped page
+ * HTML to warn (never remove) on a scoped selector that matches no element.
  * @param {Assets} assets
  * @param {Paths} paths
+ * @param {string} pageHtml Assembled page HTML (carries the `data-wd-scope` stamps).
+ * @param {Set<string>} warned Cross-route dedupe set for emitted hints.
  * @returns {void}
  */
-function emitAssets(assets, paths) {
+function emitAssets(assets, paths, pageHtml, warned) {
   for (const [source, href] of assets.files) {
     const out = path.join(paths.distRoot, href);
     fs.mkdirSync(path.dirname(out), { recursive: true });
     if (source.endsWith(".skin")) {
-      fs.writeFileSync(out, compileSkin(fs.readFileSync(source, "utf8")));
+      const src = fs.readFileSync(source, "utf8");
+      if (assets.scopedSkins.has(source)) {
+        const rel = path.relative(paths.cwd, source).replaceAll(path.sep, "/");
+        const scope = scopeIdFor(rel);
+        /** @type {Set<string>} */
+        const subjects = new Set();
+        fs.writeFileSync(out, compileSkin(src, { scope, subjects }));
+        warnUnusedScoped(subjects, scope, pageHtml, path.basename(source), warned);
+      } else {
+        fs.writeFileSync(out, compileSkin(src));
+      }
     } else {
       fs.copyFileSync(source, out);
     }
   }
 }
 
+/**
+ * Warn (do NOT remove) when a scoped selector's subject never appears in its
+ * stamped subtree — a likely typo or stale rule. We only have a class/element/id
+ * to look for, so we scan the elements actually stamped with THIS scope id in the
+ * assembled page and check each subject against them. A colocated `.js` may add
+ * classes at runtime, so this stays advisory: the rule is always emitted. An empty
+ * subject token (a bare attribute-selector subject) is unknowable here and skipped.
+ * @param {Set<string>} subjects Scoped subject tokens (`.card`, `h2`, `#id`).
+ * @param {string} scope Scope id.
+ * @param {string} pageHtml Assembled page HTML.
+ * @param {string} skinName Skin filename for the message.
+ * @param {Set<string>} warned Cross-route dedupe set.
+ * @returns {void}
+ */
+function warnUnusedScoped(subjects, scope, pageHtml, skinName, warned) {
+  // The opening tags carrying this scope id — the only elements the scoped
+  // stylesheet can match. One scan, reused for every subject.
+  const stamped = pageHtml.match(
+    new RegExp(`<[a-zA-Z][\\w-]*[^>]*\\bdata-wd-scope="${scope}"[^>]*>`, "g")
+  );
+  const tags = stamped ?? [];
+  for (const subject of subjects) {
+    if (!subject) continue;
+    const present = tags.some((tag) => subjectMatchesTag(subject, tag));
+    if (present) continue;
+    const warning = `scoped selector "${subject}" in ${skinName} matches no element`;
+    if (warned.has(warning)) continue;
+    warned.add(warning);
+    console.warn(`hint: ${warning}`);
+  }
+}
+
+/**
+ * Whether a scoped subject token (`.card` / `#id` / a bare tag like `h2`) could
+ * match a single stamped opening tag. Class subjects look in the tag's `class`
+ * attribute; id subjects in `id`; a bare tag compares the element name.
+ * @param {string} subject
+ * @param {string} tag A single opening tag string.
+ * @returns {boolean}
+ */
+function subjectMatchesTag(subject, tag) {
+  if (subject.startsWith(".")) {
+    const cls = subject.slice(1);
+    const m = tag.match(/\bclass\s*=\s*"([^"]*)"/);
+    return m ? m[1].split(/\s+/).includes(cls) : false;
+  }
+  if (subject.startsWith("#")) {
+    const m = tag.match(/\bid\s*=\s*"([^"]*)"/);
+    return m ? m[1] === subject.slice(1) : false;
+  }
+  const name = tag.match(/^<([a-zA-Z][\w-]*)/);
+  return name ? name[1].toLowerCase() === subject.toLowerCase() : false;
+}
+
 /**
  * Copy non-page shelf assets (JSON data, media) into `dist/__wd`.
  * @param {Paths} paths