@zvndev/darkmown 1.1.0 → 1.2.0

package/src/compiler/loops.js

@@ -29,15 +29,16 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
  */
 
 // The fixed corrective suggestion shown for any malformed @loop header.
-const LOOP_USAGE = "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N]";
+const LOOP_USAGE =
+  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [sortable]";
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
- * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N]`.
+ * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [sortable]`.
  * @param {string} tail Everything after `@loop src into item`.
  * @param {string} itemName
  * @param {Ctx} ctx
- * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean }}
+ * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean }}
  */
 function parseLoopClauses(tail, itemName, ctx) {
   // Peel clauses off the END in reverse fixed-order (limit, offset, reverse,
@@ -51,11 +52,23 @@ function parseLoopClauses(tail, itemName, ctx) {
   /** @type {NumArg|null} */ let offset = null;
   /** @type {NumArg|null} */ let limit = null;
   let refsState = false;
+  let sortable = false;
   /** @returns {never} */
   const bad = () => {
     throw new Error(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`);
   };
 
+  // `sortable` is a position-independent flag (drag-reorder); peel it wherever it
+  // sits so the rest of the fixed-order parse is unaffected. handleLoop rejects it
+  // when combined with where/sort/reverse/offset/limit.
+  const sm = s.match(/(^|\s)sortable(?=\s|$)/);
+  if (sm) {
+    sortable = true;
+    s = (s.slice(0, sm.index) + s.slice((sm.index ?? 0) + sm[0].length))
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
   let m = s.match(/(^|\s)limit\s+(\d+|[A-Za-z_$][\w$]*)$/);
   if (m) {
     limit = parseNumArg(m[2], ctx);
@@ -96,7 +109,7 @@ function parseLoopClauses(tail, itemName, ctx) {
     // predicate means a clause was written before `where` finished (wrong order).
     if (/(^|\s)(sort\s+by\s|reverse(\s|$))/.test(where)) bad();
   }
-  return { where, sort, reverse, offset, limit, refsState };
+  return { where, sort, reverse, offset, limit, refsState, sortable };
 }
 
 /**
@@ -193,8 +206,27 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
   const itemName = match[2];
   const clauses = match[3]
     ? parseLoopClauses(match[3], itemName, ctx)
-    : { where: null, sort: null, reverse: false, offset: null, limit: null, refsState: false };
+    : {
+        where: null,
+        sort: null,
+        reverse: false,
+        offset: null,
+        limit: null,
+        refsState: false,
+        sortable: false
+      };
   const where = clauses.where ? compilePredicate(clauses.where, itemName, ctx) : null;
+  // `sortable` reorders the list directly, so it can't combine with a clause that
+  // re-derives the visible order (where/sort/reverse) or shows a partial view
+  // (offset/limit) — those would break the 1:1 DOM↔array index mapping.
+  if (
+    clauses.sortable &&
+    (where || clauses.sort || clauses.reverse || clauses.offset || clauses.limit)
+  ) {
+    throw new Error(
+      `@loop sortable cannot combine with where/sort/reverse/offset/limit in ${ctx.file}. ${LOOP_USAGE}`
+    );
+  }
   /** @type {LoopOpts} */
   const opts = {
     where,
@@ -203,7 +235,8 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     offset: clauses.offset,
     limit: clauses.limit,
     empty: emptyLines,
-    clauseRefsState: clauses.refsState
+    clauseRefsState: clauses.refsState,
+    sortable: clauses.sortable
   };
 
   if (
@@ -242,6 +275,11 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
+      if (opts.sortable) {
+        throw new Error(
+          `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`
+        );
+      }
       return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
     }
   }
@@ -298,6 +336,11 @@ function pipelineRows(rows, where, opts, ctx) {
  * @returns {string}
  */
 function loopOverData(rows, itemName, bodyLines, ctx, opts) {
+  if (opts.sortable) {
+    throw new Error(
+      `@loop sortable requires a :state or :store list to reorder, not a JSON file or in-scope value, in ${ctx.file}. ${LOOP_USAGE}`
+    );
+  }
   // Reactive when the where reads state OR an offset/limit references a state key.
   const reactive = (opts.where && opts.where.refsState) || opts.clauseRefsState;
   if (reactive) return reactiveLoop(null, itemName, bodyLines, ctx, { ...opts, data: rows });
@@ -396,7 +439,8 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
           ? { kind: "literal", value: num(limit) ?? allRows.length }
           : limit,
       empty: null,
-      clauseRefsState: false
+      clauseRefsState: false,
+      sortable: false
     },
     ctx
   );
@@ -421,9 +465,14 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
       ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()
       : initial;
 
+  // `sortable` tags the region for the drag-reorder behavior (emitted only here)
+  // and points it at the state key whose list it rewrites on drop.
+  const sortable = opts?.sortable || false;
+  if (sortable && key) ctx.comp.assets.behaviors.add("sortable");
   const attrs =
     loopClauseAttrs({ where, sort, reverse, offset, limit }) +
-    (baked ? ` data-wd-loop-data="${escapeHtml(JSON.stringify(baked))}"` : "");
+    (baked ? ` data-wd-loop-data="${escapeHtml(JSON.stringify(baked))}"` : "") +
+    (sortable && key ? ` data-wd-sortable="${escapeHtml(key)}"` : "");
   return `<div data-wd-loop="${escapeHtml(key || "")}"${attrs}><template data-wd-loop-template>${itemTemplate}</template>${emptyTemplate}<${wrapperTag} data-wd-loop-out>${initialOut}</${wrapperTag}></div>`;
 }
 

package/src/compiler/page.js

@@ -61,9 +61,15 @@ export function compilePage(file, context) {
   const cssLinks = [...compiled.assets.skins]
     .map((href) => `<link rel="stylesheet" href="${href}">`)
     .join("\n");
-  const scriptSrcs = compiled.assets.runtime
-    ? ["/__wd/runtime.js", ...compiled.assets.scripts]
-    : [...compiled.assets.scripts];
+  // Pay-for-what-you-use behavior modules (slider is compile-time and never here;
+  // sortable/carousel each emit one) load after the runtime — sortable depends on
+  // `window.wd` — and before any colocated page script.
+  const behaviorSrcs = [...compiled.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
+  const scriptSrcs = [
+    ...(compiled.assets.runtime ? ["/__wd/runtime.js"] : []),
+    ...behaviorSrcs,
+    ...compiled.assets.scripts
+  ];
   const scripts = scriptSrcs
     .map((src) => `<script type="module" src="${src}"></script>`)
     .join("\n");

package/src/deploy.js

@@ -0,0 +1,174 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { buildSite } from "./builder.js";
+import { BASE_SECURITY_HEADERS, REACTIVE_CSP } from "./headers.js";
+
+/** The platforms `darkmown deploy` knows how to drive. */
+export const DEPLOY_TARGETS = ["vercel", "cloudflare"];
+
+/**
+ * Deploy a Darkmown site to a platform by wrapping its CLI. The build is
+ * target-aware (Cloudflare gets the `dist/_worker.js` for `api/*`), platform
+ * config is written if missing, then the platform CLI runs via `npx`.
+ *
+ * The process spawn is injected (`run`) so this is unit-testable without touching
+ * the network; the binary defaults to {@link spawnProcess}.
+ * @param {object} opts
+ * @param {string} opts.cwd Project directory.
+ * @param {string} opts.target One of {@link DEPLOY_TARGETS}.
+ * @param {boolean} [opts.prod] Promote to production.
+ * @param {(msg: string) => void} opts.log Progress sink.
+ * @param {(file: string, args: string[], options: object) => Promise<{ code: number, stdout: string, stderr: string }>} [opts.run]
+ * @param {string} [opts.projectName] Cloudflare Pages project name (defaults to package.json name).
+ * @returns {Promise<{ url: string | null }>}
+ */
+export async function deploy({ cwd, target, prod = false, log, run = spawnProcess, projectName }) {
+  if (!DEPLOY_TARGETS.includes(target)) {
+    throw new Error(`Unknown deploy target "${target}". Use one of: ${DEPLOY_TARGETS.join(", ")}.`);
+  }
+
+  ensurePlatformConfig(cwd, target);
+  log(`Building for ${target}…`);
+  buildSite(cwd, { target });
+
+  const plan = deployCommand({ target, prod, name: projectName || packageName(cwd) });
+  log(`$ ${plan.file} ${plan.args.join(" ")}`);
+  const result = await run(plan.file, plan.args, { cwd });
+  const output = `${result.stdout}\n${result.stderr}`;
+
+  if (result.code !== 0) {
+    // Matches both Vercel ("Not authenticated. Please log in.") and wrangler
+    // ("you are not logged in", "Authentication error", "run `wrangler login`",
+    // "You need to log in first") auth-failure wording.
+    if (
+      /not authenticated|not logged in|please log ?in|unauthorized|no auth|log ?in first|authentication (?:error|failed)|wrangler login/i.test(
+        output
+      )
+    ) {
+      throw new Error(
+        `The ${target} CLI is not signed in. Run \`${plan.loginHint}\` (try \`! ${plan.loginHint}\` in this session), then re-run \`darkmown deploy ${target}\`.`
+      );
+    }
+    throw new Error(`${target} deploy failed (exit ${result.code}).`);
+  }
+
+  const url = plan.parseUrl(output);
+  if (url) log(`Deployed → ${url}`);
+  else log("Deploy finished (no URL detected in the CLI output).");
+  return { url };
+}
+
+/**
+ * Build the platform CLI invocation: binary, args, login hint, and a URL parser.
+ * @param {{ target: string, prod: boolean, name: string }} opts
+ * @returns {{ file: string, args: string[], loginHint: string, parseUrl: (out: string) => string | null }}
+ */
+function deployCommand({ target, prod, name }) {
+  if (target === "vercel") {
+    const args = ["--yes", "vercel", "deploy", "--yes"];
+    if (prod) args.push("--prod");
+    return {
+      file: "npx",
+      args,
+      loginHint: "npx vercel login",
+      parseUrl: (out) => firstMatch(out, /https:\/\/[^\s]*\.vercel\.app[^\s]*/)
+    };
+  }
+  // cloudflare — `--branch main` promotes to production only if the project's
+  // configured production branch is literally `main` (Cloudflare's default).
+  const args = ["--yes", "wrangler", "pages", "deploy", "dist", "--project-name", name];
+  if (prod) args.push("--branch", "main");
+  return {
+    file: "npx",
+    args,
+    loginHint: "npx wrangler login",
+    parseUrl: (out) => firstMatch(out, /https:\/\/[^\s]*\.pages\.dev[^\s]*/)
+  };
+}
+
+/**
+ * Ensure the platform has the config it needs. Vercel reads `vercel.json` BEFORE
+ * the build, so write a sane default if absent (never overwrite). Cloudflare needs
+ * nothing extra — the build emits `dist/_worker.js` + `dist/_headers`.
+ * @param {string} cwd
+ * @param {string} target
+ * @returns {void}
+ */
+function ensurePlatformConfig(cwd, target) {
+  if (target !== "vercel") return;
+  const file = path.join(cwd, "vercel.json");
+  if (fs.existsSync(file)) return;
+  const config = {
+    $schema: "https://openapi.vercel.sh/vercel.json",
+    framework: null,
+    buildCommand: "npm run build",
+    outputDirectory: "dist",
+    cleanUrls: true,
+    trailingSlash: false,
+    headers: [
+      {
+        source: "/(.*)",
+        headers: [
+          ...Object.entries(BASE_SECURITY_HEADERS).map(([key, value]) => ({ key, value })),
+          { key: "Content-Security-Policy", value: REACTIVE_CSP }
+        ]
+      }
+    ]
+  };
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+/**
+ * Spawn a process, streaming its output to the terminal while capturing it for
+ * URL parsing. Resolves (never rejects) with the exit code + captured streams.
+ * @param {string} file
+ * @param {string[]} args
+ * @param {object} options
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+export function spawnProcess(file, args, options) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(file, args, { ...options, stdio: ["inherit", "pipe", "pipe"] });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      process.stdout.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      process.stderr.write(chunk);
+    });
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    child.on("error", (err) => resolve({ code: 1, stdout, stderr: `${stderr}${err}` }));
+  });
+}
+
+/**
+ * @param {string} text
+ * @param {RegExp} re
+ * @returns {string | null}
+ */
+function firstMatch(text, re) {
+  const match = text.match(re);
+  // The greedy `[^\s]*` can swallow trailing sentence punctuation (e.g. a period
+  // after the URL in "Deployed to https://x.pages.dev."); strip it off.
+  return match ? match[0].replace(/[.,;:)\]}'"]+$/, "") : null;
+}
+
+/**
+ * The project's package.json `name`, or the directory name, as a Cloudflare Pages
+ * project slug.
+ * @param {string} cwd
+ * @returns {string}
+ */
+function packageName(cwd) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    if (pkg.name) return String(pkg.name).replace(/^@[^/]+\//, "");
+  } catch {
+    /* no package.json — fall back to the directory name */
+  }
+  return path.basename(cwd) || "darkmown-site";
+}

package/src/headers.js

@@ -22,6 +22,9 @@
  *   - `:video`/`:audio` allow relative or `http(s)` sources — `media-src 'self' https:`.
  *   - `:embed` rewrites to exactly the YouTube no-cookie and Vimeo player origins,
  *     so `frame-src` pre-authorizes those two hosts (and nothing else).
+ *   - A native `:form action="/api/…"` POSTs same-origin, so `form-action 'self'`
+ *     authorizes it (and blocks a form exfiltrating to a third-party origin). Apps
+ *     posting to a remote backend widen this alongside `connect-src`.
  *
  * Static pages (zero framework JS) still emit inline `<style>` and an inline
  * `<script type="speculationrules">`, so they keep `'unsafe-inline'`, but they
@@ -51,6 +54,7 @@ const COMMON_CSP_DIRECTIVES = [
   CONNECT_SRC,
   "object-src 'none'",
   "base-uri 'self'",
+  "form-action 'self'",
   "frame-ancestors 'self'"
 ];
 

package/src/runtime.js

@@ -587,7 +587,9 @@ function render() {
 document.addEventListener("input", (event) => {
   const input = /** @type {HTMLInputElement | null} */ (/** @type {Element} */ (event.target)?.closest("[data-wd-bind-input]"));
   if (!input) return;
-  state[input.getAttribute("data-wd-bind-input") || ""] = input.value;
+  // A `:slider` binds a range input: keep state numeric so `:computed`/math see a
+  // number, not the DOM's string `.value`. Other inputs stay strings as before.
+  state[input.getAttribute("data-wd-bind-input") || ""] = input.type === "range" ? input.valueAsNumber : input.value;
   savePersisted();
   render();
   checkRefetch();

package/src/scaffold.js

@@ -1,24 +1,60 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(moduleDir, "templates");
 
 const darkmownVersion = JSON.parse(
   fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")
 ).version;
 
 /**
- * Scaffold a new Darkmown project into `root`, creating files that don't exist.
+ * List the available scaffold templates (directory names under `src/templates`).
+ * @returns {string[]}
+ */
+export function availableTemplates() {
+  if (!fs.existsSync(templatesDir)) return [];
+  return fs
+    .readdirSync(templatesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/**
+ * Scaffold a new Darkmown project into `root` from a template, creating files
+ * that don't already exist (never overwriting). `package.json` is generated (so
+ * the name tracks the directory and the `@zvndev/darkmown` dep pins the installed
+ * version); every other file is copied verbatim from the chosen template.
  * @param {string} root Absolute path to the target project directory.
- * @returns {{ root: string }}
+ * @param {{ template?: string }} [options] `template` defaults to `"starter"`.
+ * @returns {{ root: string, template: string }}
  */
-export function initProject(root) {
+export function initProject(root, options = {}) {
+  const template = options.template || "starter";
+  const templateDir = path.join(templatesDir, template);
+  if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
+    const list = availableTemplates().join(", ");
+    throw new Error(
+      `Unknown template "${template}". Available templates: ${list || "(none)"}. ` +
+        "Use: darkmown init [dir] --template <name>"
+    );
+  }
+
   fs.mkdirSync(root, { recursive: true });
+
+  // package.json is generated, not copied: the name follows the target directory,
+  // the dep pins the installed Darkmown version, and `type: "module"` makes a
+  // project `api/*.js` import as ESM in `darkmown dev` and on every host.
   writeNew(
     root,
     "package.json",
-    JSON.stringify(
+    `${JSON.stringify(
       {
         name: packageNameFromRoot(root),
         private: true,
+        type: "module",
         scripts: {
           dev: "darkmown dev",
           build: "darkmown build",
@@ -30,161 +66,57 @@ export function initProject(root) {
       },
       null,
       2
-    )
-  );
-  writeNew(
-    root,
-    "site/pages/index.wd",
-    [
-      "---",
-      "title: My Darkmown site",
-      "---",
-      "",
-      "@include /nav.wd",
-      "",
-      "<main>",
-      "",
-      "# My Darkmown site",
-      "",
-      "Plain Markdown works. Rename to `.wd` when you want directives.",
-      "",
-      ":state count = 0",
-      "",
-      "Count: { count }",
-      "",
-      ':button "Increment" -> count++',
-      "",
-      ':state todos = ["Write a page"]',
-      "",
-      "@loop todos into todo",
-      "- { todo }",
-      "@endloop",
-      "",
-      ':button "Add" -> todos += "Add a loop"',
-      "",
-      "</main>"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "site/pages/index.skin",
-    [
-      "tokens",
-      "  ink #172026",
-      "  paper #f7f2e8",
-      "  accent #0f8b8d",
-      "",
-      "page",
-      "  margin 0",
-      "  font ui-sans-serif, system-ui, sans-serif",
-      "  color $ink",
-      "  bg $paper",
-      "",
-      "main",
-      "  max-width 760px",
-      "  margin 0 auto",
-      "  padding 3rem 1.5rem",
-      "",
-      "nav",
-      "  display flex",
-      "  align-items center",
-      "  justify-content space-between",
-      "  gap 1rem",
-      "  max-width 760px",
-      "  margin 0 auto",
-      "  padding 1.25rem 1.5rem",
-      "",
-      "nav strong",
-      "  font-size 1.1rem",
-      "",
-      "nav .links",
-      "  display flex",
-      "  gap 1.25rem",
-      "",
-      "nav a",
-      "  color $ink",
-      "  text-decoration none",
-      "  opacity .8",
-      "",
-      "nav a:hover",
-      "  opacity 1",
-      "  color $accent",
-      "",
-      "button",
-      "  bg $accent",
-      "  color white",
-      "  border 0",
-      "  padding .75rem 1rem",
-      "  radius 8px"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "site/_/nav.wd",
-    [
-      "<nav>",
-      "  <strong>My site</strong>",
-      '  <span class="links">',
-      '    <a href="/">Home</a>',
-      '    <a href="/about/">About</a>',
-      "  </span>",
-      "</nav>"
-    ].join("\n")
+    )}\n`
   );
-  writeNew(
-    root,
-    "site/pages/about.md",
-    [
-      "---",
-      "title: About",
-      "---",
-      "",
-      "# About",
-      "",
-      "This page is plain Markdown (`.md`) — strict CommonMark, zero framework JavaScript.",
-      "Rename it to `.wd` when you want directives like state, loops, or forms.",
-      "",
-      "[Back home](/)"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "README.md",
-    [
-      "# My Darkmown site",
-      "",
-      "Run `npm install` and `npm run dev` to start the live compiler.",
-      "",
-      "## Commands",
-      "",
-      "- `npm run dev` — live compiler on http://localhost:5173 with hot reload.",
-      "- `npm run build` — compile the site to `dist/`.",
-      "- `npm run preview` — serve the built `dist/` locally.",
-      "",
-      "## Layout",
-      "",
-      "- Pages live in `site/pages`.",
-      "- Shared includes live in `site/_`.",
-      "- Hidden route files start with `.` or `-`.",
-      "- Colocated `index.skin` and `index.js` attach automatically.",
-      "- Any other file under `site/pages` (images, fonts, …) copies to `dist/` at its own path."
-    ].join("\n")
-  );
-  return { root };
+
+  for (const rel of walk(templateDir)) {
+    copyNew(path.join(templateDir, rel), path.join(root, rel));
+  }
+  return { root, template };
 }
 
 /**
- * Write a file relative to `root` only if it does not already exist.
+ * Write a file relative to `root` only if it does not already exist. Content is
+ * written verbatim (callers include any trailing newline).
  * @param {string} root Project root directory.
  * @param {string} file Path relative to `root`.
- * @param {string} content File contents (a trailing newline is added).
+ * @param {string} content File contents.
  * @returns {void}
  */
 function writeNew(root, file, content) {
   const target = path.join(root, file);
   if (fs.existsSync(target)) return;
   fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, `${content}\n`);
+  fs.writeFileSync(target, content);
+}
+
+/**
+ * Copy a template file to `dest`, preserving bytes, only if `dest` is absent.
+ * @param {string} source
+ * @param {string} dest
+ * @returns {void}
+ */
+function copyNew(source, dest) {
+  if (fs.existsSync(dest)) return;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(source, dest);
+}
+
+/**
+ * Relative paths of every file under `dir` (POSIX-separated), recursively.
+ * @param {string} dir
+ * @param {string} [base]
+ * @returns {string[]}
+ */
+function walk(dir, base = dir) {
+  /** @type {string[]} */
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(abs, base));
+    else files.push(path.relative(base, abs).replaceAll(path.sep, "/"));
+  }
+  return files;
 }
 
 /**

package/src/templates/blog/README.md

@@ -0,0 +1,25 @@
+# Blog — a Darkmown template
+
+A markdown-native blog. Posts are plain `.md` files in `site/pages/posts/`; the
+home page loops `site/_/posts.json` to list them. Static pages, zero JavaScript.
+
+## Add a post
+
+1. Create `site/pages/posts/<slug>.md` with a `title` in frontmatter.
+2. Add an entry to `site/_/posts.json` (`slug`, `url`, `title`, `date`, `excerpt`).
+
+## Commands
+
+- `npm run dev` — live compiler on http://localhost:5173.
+- `npm run build` — compile to `dist/`.
+- `npm run preview` — serve the built `dist/` locally.
+
+## Deploy
+
+```sh
+npx darkmown deploy vercel       # or: npx darkmown deploy cloudflare
+```
+
+[![Deploy to Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=YOUR_REPO_URL)
+&nbsp;
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=YOUR_REPO_URL)

package/src/templates/blog/site/_/nav.wd

@@ -0,0 +1,6 @@
+<nav>
+  <strong>My Blog</strong>
+  <span class="links">
+    <a href="/">Posts</a>
+  </span>
+</nav>

package/src/templates/blog/site/_/posts.json

@@ -0,0 +1,16 @@
+[
+  {
+    "slug": "hello-darkmown",
+    "url": "/posts/hello-darkmown/",
+    "title": "Hello, Darkmown",
+    "date": "2026-06-15",
+    "excerpt": "Why I rewrote my blog as plain Markdown files — and shipped zero framework JavaScript."
+  },
+  {
+    "slug": "markdown-native",
+    "url": "/posts/markdown-native/",
+    "title": "Markdown-native, by default",
+    "date": "2026-06-01",
+    "excerpt": "Every post is a .md file. The index is one .wd loop over this manifest. That's the whole site."
+  }
+]