@zvndev/darkmown 2.10.0 → 2.11.0

package/src/mcp.js

@@ -0,0 +1,287 @@
+// ---------------------------------------------------------------------------
+// MCP (Model Context Protocol) server, stdio transport, hand-rolled.
+//
+// MCP over stdio is newline-delimited JSON-RPC 2.0: the client (Claude Code,
+// Codex, Cursor, …) writes one JSON message per line on the server's stdin and
+// reads one JSON response per line from its stdout. Everything else a server
+// wants to say (startup banners, logs) goes to stderr — a single stray byte on
+// stdout corrupts the frame stream, so `serveMcp` only ever writes responses
+// there.
+//
+// This is a focused implementation of the subset a doc/validation server
+// needs, protocol revision 2024-11-05:
+//
+//   initialize                 handshake: protocolVersion, capabilities, serverInfo
+//   notifications/initialized  client ack — no response (as for every notification)
+//   ping                       liveness — answers {}
+//   tools/list                 the five Darkmown tools, with inputSchema
+//   tools/call                 run one tool, answer MCP text content
+//   resources/list             the darkmown://docs/* resources
+//   resources/read             one resource's markdown text
+//
+// Deliberately NOT implemented (noted in the handshake's capabilities by their
+// absence): prompts, logging, completion, sampling, subscriptions, and
+// BATCHED requests — a JSON array on one line is answered with a single
+// -32600 Invalid Request, which the spec permits a server to do. Tool/resource
+// definitions are static for the life of the process, so the optional
+// list-change notifications never fire.
+//
+// The module is dependency-free (Node built-ins only) and side-effect-free on
+// import: `serveMcp` is called explicitly by the CLI's `mcp` command, and the
+// dispatcher is a pure function tests drive in-process.
+// ---------------------------------------------------------------------------
+
+/** The one MCP protocol revision this server speaks. */
+export const PROTOCOL_VERSION = "2024-11-05";
+
+// Standard JSON-RPC 2.0 error codes.
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+
+/**
+ * One tool the server exposes over `tools/list` / `tools/call`.
+ * @typedef {object} McpTool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} inputSchema A JSON Schema object describing the arguments.
+ * @property {(args: Record<string, unknown>) => McpToolOutcome} run
+ */
+
+/**
+ * What a tool run returns. `text` becomes the first MCP text content item; a
+ * defined `data` is appended as a second text item carrying pretty-printed
+ * JSON, so an agent gets both the human-readable answer and the structured
+ * one. `isError` marks the result as a tool-level failure (a bad argument),
+ * never a protocol error — those are JSON-RPC errors on the envelope.
+ * @typedef {object} McpToolOutcome
+ * @property {string} text
+ * @property {object} [data]
+ * @property {boolean} [isError]
+ */
+
+/**
+ * One resource the server exposes over `resources/list` / `resources/read`.
+ * @typedef {object} McpResource
+ * @property {string} uri
+ * @property {string} name
+ * @property {string} description
+ * @property {string} mimeType
+ * @property {() => string} read
+ */
+
+/**
+ * Everything the dispatcher needs to answer. Constructed by
+ * `mcpConfig()` in src/mcp-tools.js; injected here so this module stays a
+ * transport + envelope layer with no knowledge of Darkmown's docs.
+ * @typedef {object} McpConfig
+ * @property {{ name: string, version: string }} serverInfo
+ * @property {McpTool[]} tools
+ * @property {McpResource[]} resources
+ */
+
+/**
+ * A JSON-RPC 2.0 message as it arrives on the wire. The server is liberal in
+ * what it accepts: `id` may be a string, a number, or absent (a notification).
+ * @typedef {{ jsonrpc?: string, id?: string | number | null, method?: unknown, params?: unknown }} McpMessage
+ */
+
+/**
+ * Create the request dispatcher: one JSON-RPC message in, one response (or
+ * `null` for a notification, which must never be answered) out.
+ *
+ * @param {McpConfig} config
+ * @returns {(message: unknown) => object | null}
+ */
+export function createDispatcher({ serverInfo, tools, resources }) {
+  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
+  const resourcesByUri = new Map(resources.map((resource) => [resource.uri, resource]));
+
+  /**
+   * @param {string | number | null} id
+   * @param {unknown} value
+   */
+  const ok = (id, value) => ({ jsonrpc: "2.0", id, result: value });
+  /**
+   * @param {string | number | null} id
+   * @param {number} code
+   * @param {string} message
+   */
+  const fail = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+  /**
+   * `tools/call`: find the tool, run it, shape the MCP result. A tool that
+   * throws is a tool-level error result (the spec's `isError` channel), not a
+   * protocol error — the client asked a fair question and the tool failed.
+   * @param {string | number | null} id
+   * @param {unknown} params
+   */
+  function callTool(id, params) {
+    const args = /** @type {{ name?: unknown, arguments?: unknown }} */ (
+      params && typeof params === "object" ? params : {}
+    );
+    const tool = typeof args.name === "string" ? toolsByName.get(args.name) : undefined;
+    if (!tool) {
+      const known = tools.map((t) => t.name).join(", ");
+      return fail(id, INVALID_PARAMS, `Unknown tool: ${String(args.name)}. Available: ${known}`);
+    }
+    /** @type {McpToolOutcome} */
+    let outcome;
+    try {
+      outcome = tool.run(
+        /** @type {Record<string, unknown>} */ (
+          args.arguments && typeof args.arguments === "object" ? args.arguments : {}
+        )
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return ok(id, {
+        content: [{ type: "text", text: `Tool "${tool.name}" failed: ${message}` }],
+        isError: true
+      });
+    }
+    const content = [{ type: "text", text: outcome.text }];
+    if (outcome.data !== undefined) {
+      content.push({ type: "text", text: JSON.stringify(outcome.data, null, 2) });
+    }
+    return ok(id, { content, ...(outcome.isError ? { isError: true } : {}) });
+  }
+
+  /**
+   * `resources/read`: one resource's full text. An unknown URI is an invalid
+   * params error naming what the server actually has.
+   * @param {string | number | null} id
+   * @param {unknown} params
+   */
+  function readResource(id, params) {
+    const args = /** @type {{ uri?: unknown }} */ (
+      params && typeof params === "object" ? params : {}
+    );
+    const resource = typeof args.uri === "string" ? resourcesByUri.get(args.uri) : undefined;
+    if (!resource) {
+      const known = resources.map((r) => r.uri).join(", ");
+      return fail(id, INVALID_PARAMS, `Unknown resource: ${String(args.uri)}. Available: ${known}`);
+    }
+    return ok(id, {
+      contents: [{ uri: resource.uri, mimeType: resource.mimeType, text: resource.read() }]
+    });
+  }
+
+  /**
+   * Dispatch one decoded message. Returns the response to write back, or
+   * `null` when the message is a notification (answered with silence, per
+   * JSON-RPC) or otherwise needs no reply.
+   * @param {unknown} message
+   * @returns {object | null}
+   */
+  function handle(message) {
+    if (!message || typeof message !== "object") {
+      // A bare scalar, or a JSON array (a batch — not supported): one error.
+      return fail(null, INVALID_REQUEST, "Invalid Request: expected a JSON-RPC object");
+    }
+    const { id, method, params } = /** @type {McpMessage} */ (message);
+    if (typeof method !== "string") {
+      return fail(id ?? null, INVALID_REQUEST, "Invalid Request: missing method");
+    }
+    // No id means notification: `notifications/initialized` and anything else
+    // the client fires one-way. Notifications are never answered, even when
+    // the method is unknown.
+    if (id === undefined || id === null) return null;
+
+    switch (method) {
+      case "initialize":
+        return ok(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {
+            tools: { listChanged: false },
+            resources: { listChanged: false }
+          },
+          serverInfo
+        });
+      case "ping":
+        return ok(id, {});
+      case "tools/list":
+        return ok(id, {
+          tools: tools.map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema
+          }))
+        });
+      case "tools/call":
+        return callTool(id, params);
+      case "resources/list":
+        return ok(id, {
+          resources: resources.map(({ uri, name, description, mimeType }) => ({
+            uri,
+            name,
+            description,
+            mimeType
+          }))
+        });
+      case "resources/read":
+        return readResource(id, params);
+      default:
+        return fail(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+  }
+
+  return handle;
+}
+
+/**
+ * Run the stdio loop: read newline-delimited JSON-RPC from `input`, write one
+ * JSON response per line to `output`. Resolves when `input` ends, which is
+ * how an MCP host stops a stdio server.
+ *
+ * A line that is not valid JSON answers with a -32700 Parse error and the loop
+ * carries on — one garbage line from a misbehaving client must not kill the
+ * server. A trailing partial line at end-of-input is answered too: MCP clients
+ * always terminate frames, but a hand-rolled `echo '{…}' | darkmown mcp` smoke
+ * test may not.
+ *
+ * @param {{ input: NodeJS.ReadableStream, output: NodeJS.WritableStream,
+ *   dispatcher: (message: unknown) => object | null }} io
+ * @returns {Promise<{ command: "mcp" }>}
+ */
+export function serveMcp({ input, output, dispatcher }) {
+  const send = (/** @type {object} */ message) => {
+    output.write(`${JSON.stringify(message)}\n`);
+  };
+  const answer = (/** @type {string} */ line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    /** @type {unknown} */
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch {
+      send({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: PARSE_ERROR, message: "Parse error: line is not valid JSON" }
+      });
+      return;
+    }
+    const response = dispatcher(message);
+    if (response) send(response);
+  };
+
+  let buffer = "";
+  return new Promise((resolve) => {
+    input.on("data", (chunk) => {
+      buffer += chunk;
+      let index = buffer.indexOf("\n");
+      while (index !== -1) {
+        answer(buffer.slice(0, index));
+        buffer = buffer.slice(index + 1);
+        index = buffer.indexOf("\n");
+      }
+    });
+    input.on("end", () => {
+      if (buffer) answer(buffer);
+      resolve({ command: "mcp" });
+    });
+  });
+}

package/src/router.js

@@ -88,6 +88,11 @@ export function isDraft(meta) {
 
 /**
  * Derive a public route path from a source file path.
+ *
+ * Fail-closed on control/whitespace characters: the route string flows RAW
+ * into generated config (`dist/_headers` blocks, llms.txt lines), where a
+ * newline in a filename would inject whole config lines. Rejecting here, at
+ * the one route-derivation chokepoint, protects every downstream sink at once.
  * @param {string} routesRoot Absolute path to `site/pages`.
  * @param {string} file Absolute path to the source file.
  * @returns {string}
@@ -98,9 +103,20 @@ export function routeFromFile(routesRoot, file) {
   const parts = rel.split(path.sep);
   if (parts.at(-1) === "index") parts.pop();
   const route = `/${parts.join("/")}`;
+  if (ROUTE_UNSAFE_CHARS.test(route)) {
+    throw wdError(
+      `Refusing to route ${file} — a page filename must not contain whitespace or ` +
+        "control characters: the route is written verbatim into generated config " +
+        "(dist/_headers, llms.txt), where such a character would corrupt the file.",
+      { code: "WD908", file }
+    );
+  }
   return route === "/" ? "/" : `${route}/`;
 }
 
+/** Whitespace (`\s`) and control characters (`\p{Cc}`: C0, DEL, C1) a route string must never carry. */
+const ROUTE_UNSAFE_CHARS = /[\s\p{Cc}]/u;
+
 /**
  * Map a public route to the `index.html` output path under `distRoot`.
  *

package/src/skin.js

@@ -1,6 +1,12 @@
 import crypto from "node:crypto";
 import { wdError } from "./compiler/context.js";
 
+// Concrete, compilable skins for the at-rule error hints + the error registry
+// (src/errors.js). Multi-line because both at-rules are block constructs; a
+// test in tests/skin-atrules.test.js compiles each verbatim.
+export const FONT_FACE_EXAMPLE = '@font-face\n  font-family "Newsreader"';
+export const KEYFRAMES_EXAMPLE = "@keyframes fade-in\n  to\n    opacity 1";
+
 const aliases = new Map([
   ["radius", "border-radius"],
   ["shadow", "box-shadow"],
@@ -70,28 +76,37 @@ const PAGE_LEVEL_SELECTORS = new Set(["page", "*", "html", "body", "::selection"
  * selectors), they are ALWAYS global (never scope-stamped, same contract as
  * `tokens`), and their declaration values use the same alias/`$token` pipeline.
  * @param {string} source
- * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
- *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
- *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
- *   warning, so the caller need not re-parse the source.
+ * @param {{ scope?: string, subjects?: Set<string>, file?: string }} [opts]
+ *   `scope`: the scope id enabling scoped mode. `subjects`: an optional set the
+ *   compiler fills with every scoped subject token (`.card`, `h2`, `#id`) for
+ *   the unused-selector warning, so the caller need not re-parse the source.
+ *   `file`: the skin's path, threaded into author-facing errors so they report
+ *   `file:line` (the builder always passes it; a bare call reports `on line N`).
  * @returns {string}
  */
 export function compileSkin(source, opts = {}) {
   const scope = opts.scope;
   const subjects = opts.subjects;
+  const file = opts.file;
   const lines = source
     .replace(/\r\n?/g, "\n")
-    .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
+    // Strip /* … */ block comments (any span), KEEPING their newlines so the
+    // `line` recorded below stays the true file line even past a multi-line
+    // comment.
+    .replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ""))
     .split("\n")
-    .filter((raw) => {
-      const t = raw.trim();
-      if (!t || t.startsWith("//")) return false;
+    .map((raw, index) => ({
+      indent: (raw.match(/^\s*/)?.[0] ?? "").length,
+      text: raw.trim(),
+      line: index + 1
+    }))
+    .filter(({ text }) => {
+      if (!text || text.startsWith("//")) return false;
       // Decorative divider lines (----, ====, * * *, ~~~) carry no rule and would
       // otherwise parse as a bogus selector/declaration. Anything with a letter or
       // digit is real content; punctuation-only lines are skipped.
-      return /[A-Za-z0-9]/.test(t);
-    })
-    .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
+      return /[A-Za-z0-9]/.test(text);
+    });
 
   // The opt-in marker: `scoped` must be the FIRST meaningful line (the filter
   // above has already dropped comments, blanks, and dividers). Anywhere else it
@@ -181,7 +196,7 @@ export function compileSkin(source, opts = {}) {
     const atRule = /^@(font-face|keyframes)(?:\s+(.+))?$/.exec(text);
     if (atRule) {
       const media = stack.find((frame) => frame.media)?.media;
-      const block = collectAtRule(atRule[1], atRule[2], lines, i);
+      const block = collectAtRule(atRule[1], atRule[2], lines, i, file);
       css.push(media ? `${media} {\n${block.css}\n}` : block.css);
       i = block.end;
       continue;
@@ -367,17 +382,19 @@ function normalizeSelector(text, parent) {
 const KEYFRAME_SELECTOR = /^(?:from|to|\d+(?:\.\d+)?%)(?:\s*,\s*(?:from|to|\d+(?:\.\d+)?%))*$/;
 
 /**
- * A plain Error, no WD code: the code registry (`src/errors.js`) and its drift
- * guard (`tests/error-codes.test.js`) are owned by a parallel change, so a
- * `code: "WD8xx"` here would fail the "every code thrown is registered" gate
- * and an inline throw would fail the "no author-facing throw bypasses wdError"
- * scan. Messages still lead with the construct and end with a corrective
- * example, registry-style.
- * @param {string} message
- * @returns {Error}
+ * An author-facing at-rule error, routed through `wdError` like every other
+ * compile error: it carries a registered WD8xx code (src/errors.js), the true
+ * source line, and a corrective `Use:` hint. The file is named when the caller
+ * threaded one (the builder always does); a bare `compileSkin` call has no
+ * path, so the location falls back to `on line N`.
+ * @param {string} summary What is wrong, naming the offending text.
+ * @param {import("./compiler/context.js").WdErrorInfo} wd The structured mirror;
+ *   `code` is required (every at-rule error is registered in src/errors.js).
+ * @returns {Error & { wd: import("./compiler/context.js").WdErrorInfo }}
  */
-function skinError(message) {
-  return new Error(message);
+function skinError(summary, wd) {
+  const where = wd.file ? ` in ${wd.file}:${wd.line}` : ` on line ${wd.line}`;
+  return wdError(`${summary}${where}. Use: ${wd.hint}`, wd);
 }
 
 /**
@@ -403,21 +420,28 @@ function declaration(text) {
  * `50%, 75%`), each with its own indented declarations; a keyframe selector is
  * validated against KEYFRAME_SELECTOR so it can never be misread as a
  * declaration or an element selector, and declarations cannot nest further.
+ * Every rejection is a coded WD8xx error pointing at the offending line.
  * @param {string} kind `font-face` or `keyframes`.
  * @param {string | undefined} rest Text after the at-rule keyword (the
  *   keyframes name; invalid on `@font-face`).
- * @param {{ indent: number, text: string }[]} lines Preprocessed skin lines.
+ * @param {{ indent: number, text: string, line: number }[]} lines Preprocessed
+ *   skin lines, each carrying its true 1-based file line.
  * @param {number} start Index of the at-rule line.
+ * @param {string | undefined} file The skin's path, when the caller knows it.
  * @returns {{ css: string, end: number }} `end` = last consumed line index.
  */
-function collectAtRule(kind, rest, lines, start) {
+function collectAtRule(kind, rest, lines, start, file) {
   const indent = lines[start].indent;
 
   if (kind === "font-face") {
     if (rest)
-      throw skinError(
-        `@font-face takes no name, got "${rest}" — write the descriptors indented beneath a bare @font-face line, e.g. font-family "Newsreader"`
-      );
+      throw skinError(`@font-face takes no name, got "${rest}"`, {
+        code: "WD804",
+        file,
+        line: lines[start].line,
+        hint: `write the descriptors indented beneath a bare @font-face line — e.g. font-family "Newsreader"`,
+        example: FONT_FACE_EXAMPLE
+      });
     /** @type {string[]} */
     const decls = [];
     let i = start;
@@ -425,52 +449,94 @@ function collectAtRule(kind, rest, lines, start) {
       i++;
       if (i + 1 < lines.length && lines[i + 1].indent > lines[i].indent)
         throw skinError(
-          `@font-face only takes declarations — "${lines[i].text}" opens a nested block, which is not valid inside @font-face`
+          `@font-face only takes declarations — "${lines[i].text}" opens a nested block, which is not valid inside @font-face`,
+          {
+            code: "WD804",
+            file,
+            line: lines[i].line,
+            hint: `keep every @font-face child a flat prop value declaration — e.g. font-family "Newsreader"`,
+            example: FONT_FACE_EXAMPLE
+          }
         );
       decls.push(`  ${declaration(lines[i].text)}`);
     }
     if (!decls.length)
-      throw skinError(
-        '@font-face has no declarations — indent its descriptors beneath it, e.g. font-family "Newsreader"'
-      );
+      throw skinError("@font-face has no declarations", {
+        code: "WD804",
+        file,
+        line: lines[start].line,
+        hint: `indent its descriptors beneath it — e.g. font-family "Newsreader"`,
+        example: FONT_FACE_EXAMPLE
+      });
     return { css: `@font-face {\n${decls.join("\n")}\n}`, end: i };
   }
 
-  if (!rest) throw skinError("@keyframes needs a name — e.g. @keyframes fade-in");
+  if (!rest)
+    throw skinError("@keyframes needs a name", {
+      code: "WD805",
+      file,
+      line: lines[start].line,
+      hint: "@keyframes <name> — e.g. @keyframes fade-in",
+      example: KEYFRAMES_EXAMPLE
+    });
   if (!/^-?[A-Za-z_][\w-]*$/.test(rest))
-    throw skinError(
-      `invalid @keyframes name "${rest}" — use a plain CSS identifier, e.g. @keyframes fade-in`
-    );
+    throw skinError(`invalid @keyframes name "${rest}"`, {
+      code: "WD805",
+      file,
+      line: lines[start].line,
+      hint: "name it with a plain CSS identifier — e.g. @keyframes fade-in",
+      example: KEYFRAMES_EXAMPLE
+    });
   /** @type {string[]} */
   const stops = [];
   let i = start;
   while (i + 1 < lines.length && lines[i + 1].indent > indent) {
     i++;
     const selector = lines[i].text;
+    const selectorLine = lines[i].line;
     const selectorIndent = lines[i].indent;
     if (!KEYFRAME_SELECTOR.test(selector))
-      throw skinError(
-        `"${selector}" is not a keyframe selector in @keyframes ${rest} — use from, to, or a percentage (50%, or a list like 50%, 75%)`
-      );
+      throw skinError(`"${selector}" is not a keyframe selector in @keyframes ${rest}`, {
+        code: "WD806",
+        file,
+        line: selectorLine,
+        hint: "use from, to, or a percentage (50%, or a list like 50%, 75%)",
+        example: KEYFRAMES_EXAMPLE
+      });
     /** @type {string[]} */
     const decls = [];
     while (i + 1 < lines.length && lines[i + 1].indent > selectorIndent) {
       i++;
       if (i + 1 < lines.length && lines[i + 1].indent > lines[i].indent)
         throw skinError(
-          `@keyframes declarations cannot nest — "${lines[i].text}" opens a block inside keyframe "${selector}"`
+          `@keyframes declarations cannot nest — "${lines[i].text}" opens a block inside keyframe "${selector}"`,
+          {
+            code: "WD807",
+            file,
+            line: lines[i].line,
+            hint: "keep each keyframe's declarations flat, one level beneath its selector — e.g. opacity 1",
+            example: KEYFRAMES_EXAMPLE
+          }
         );
       decls.push(`    ${declaration(lines[i].text)}`);
     }
     if (!decls.length)
-      throw skinError(
-        `keyframe "${selector}" in @keyframes ${rest} has no declarations — indent them beneath it`
-      );
+      throw skinError(`keyframe "${selector}" in @keyframes ${rest} has no declarations`, {
+        code: "WD807",
+        file,
+        line: selectorLine,
+        hint: "indent the declarations beneath the keyframe selector — e.g. opacity 1",
+        example: KEYFRAMES_EXAMPLE
+      });
     stops.push(`  ${selector} {\n${decls.join("\n")}\n  }`);
   }
   if (!stops.length)
-    throw skinError(
-      `@keyframes ${rest} has no keyframe selectors — indent from/to/percentage blocks beneath it`
-    );
+    throw skinError(`@keyframes ${rest} has no keyframe selectors`, {
+      code: "WD807",
+      file,
+      line: lines[start].line,
+      hint: "indent from/to/percentage blocks beneath it — e.g. from",
+      example: KEYFRAMES_EXAMPLE
+    });
   return { css: `@keyframes ${rest} {\n${stops.join("\n")}\n}`, end: i };
 }

package/src/statics.js

@@ -292,6 +292,7 @@ const contentTypes = {
   ".js": "text/javascript; charset=utf-8",
   ".json": "application/json",
   ".map": "application/json",
+  ".md": "text/markdown; charset=utf-8",
   ".svg": "image/svg+xml",
   ".png": "image/png",
   ".jpg": "image/jpeg",

package/src/templates/dashboard/README.md

@@ -12,7 +12,9 @@ in `darkmown dev` and on every host. Loading and error states are handled inline
 
 - `npm run dev` — live compiler + local `/api/*` runner on http://localhost:5173.
 - `npm run build` — compile to `dist/`.
-- `npm run preview` — serve the built `dist/` locally (static only; use `dev` for `/api`).
+- `npm run preview`: serve the built `dist/` locally. Since Darkmown 2.8.0 this
+  runs your `api/` functions too, so the dashboard fetches live data in preview
+  exactly like in `dev`.
 
 ## Deploy
 

package/src/templates/landing/site/pages/index.skin

@@ -164,6 +164,13 @@ input:focus-visible, textarea:focus-visible, select:focus-visible
   radius 12px
   padding 1.25rem
 
+.icon
+  color $accent
+  margin-bottom .35rem
+
+.icon svg
+  display block
+
 .feature h3
   margin .25rem 0 .5rem
 

package/src/templates/landing/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Acme — ship faster
 description: A marketing one-pager built with Darkmown. Zero framework JS on the static parts, with a testimonials carousel.
 transitions: true
+html: true
 ---
 
 @include /nav.wd
@@ -20,15 +21,21 @@ The all-in-one toolkit your team actually enjoys using.
 
 ::: features
 ::: feature
-### ⚡ Fast
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M13 2 4 14h6l-1 8 9-12h-6l1-8z"/></svg></div>
+
+### Fast
 Static pages, zero framework JavaScript. Instant loads, perfect Lighthouse.
 :::
 ::: feature
-### 🧩 Simple
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="4" width="7" height="7" rx="1.5"/><rect x="13" y="4" width="7" height="7" rx="1.5"/><rect x="4" y="13" width="7" height="7" rx="1.5"/><rect x="13" y="13" width="7" height="7" rx="1.5"/></svg></div>
+
+### Simple
 Write Markdown. Add a directive only on the pages that need interactivity.
 :::
 ::: feature
-### 🚀 Deploy anywhere
+<div class="icon"><svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 15V3"/><path d="m6 9 6-6 6 6"/><path d="M4 21h16"/></svg></div>
+
+### Deploy anywhere
 One command to Vercel or Cloudflare — your API comes along for free.
 :::
 :::

package/src/templates/store/README.md

@@ -3,7 +3,9 @@
 A storefront in Markdown: a product grid with live search, a shared `:store` cart,
 and a checkout that POSTs to a serverless function.
 
-- **Static catalog** — `site/pages/index.wd` loops `site/_/products.json`.
+- **Static catalog**: `site/pages/index.wd` loops `site/_/products.json`, rendering
+  each product through the `site/_/card.wd` include (a `defaults:` fallback plus a
+  `{ children }` slot for the add-to-cart button).
 - **Cart** — a `:store` shared across the page; add/remove with `:button`.
 - **Checkout** — `:form action="/api/checkout"` posts to `api/checkout.js`, a plain
   Web-standard `(request) => Response` function that runs in `darkmown dev` and on
@@ -13,7 +15,8 @@ and a checkout that POSTs to a serverless function.
 
 - `npm run dev` — live compiler + the local `/api/*` runner on http://localhost:5173.
 - `npm run build` — compile to `dist/`.
-- `npm run preview` — serve the built `dist/` locally (static only; use `dev` for `/api`).
+- `npm run preview`: serve the built `dist/` locally. Since Darkmown 2.8.0 this
+  runs your `api/` functions too, so checkout works in preview exactly like in `dev`.
 
 ## Deploy