@zvndev/darkmown 0.8.1 → 0.9.0

package/src/config.js

@@ -5,6 +5,20 @@ export const shelfDir = "site/_";
 export const distDir = "dist";
 export const pageExtensions = new Set([".md", ".wd"]);
 
+/**
+ * Resolved project paths used across the build pipeline.
+ * @typedef {object} Paths
+ * @property {string} cwd Project working directory.
+ * @property {string} routesRoot Absolute path to `site/pages`.
+ * @property {string} shelfRoot Absolute path to the include shelf `site/_`.
+ * @property {string} distRoot Absolute path to the build output `dist`.
+ */
+
+/**
+ * Build the absolute project paths for a given working directory.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {Paths}
+ */
 export function createPaths(cwd = process.cwd()) {
   return {
     cwd,
@@ -14,6 +28,11 @@ export function createPaths(cwd = process.cwd()) {
   };
 }
 
+/**
+ * Whether a file or directory name is hidden from routing (starts with `.`, `-`, or `_`).
+ * @param {string} name
+ * @returns {boolean}
+ */
 export function isHiddenName(name) {
   return name.startsWith(".") || name.startsWith("-") || name.startsWith("_");
 }

package/src/dev.js

@@ -1,11 +1,20 @@
 export const devClientPath = "/__wd/dev-client.js";
 export const devEventsPath = "/__wd/dev-events";
 
+/**
+ * Inject the dev-client `<script>` before `</body>` (or append it if absent).
+ * @param {string} html Page HTML to augment.
+ * @returns {string}
+ */
 export function injectDevClient(html) {
   const script = `<script type="module" src="${devClientPath}"></script>`;
   return html.includes("</body>") ? html.replace("</body>", `${script}\n</body>`) : `${html}\n${script}`;
 }
 
+/**
+ * The dev-client browser script that opens the SSE channel for live reload.
+ * @returns {string}
+ */
 export function devClientScript() {
   return `
 const source = new EventSource("${devEventsPath}");

package/src/router.js

@@ -2,10 +2,24 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHiddenName, pageExtensions } from "./config.js";
 
+/**
+ * A discovered page route: the source file and its public route path.
+ * @typedef {object} Route
+ * @property {string} file Absolute path to the source `.md`/`.wd` file.
+ * @property {string} route Public route path (always trailing-slashed, e.g. `/about/`).
+ */
+
+/**
+ * Walk `routesRoot` and collect page routes, sorted and de-duplicated.
+ * @param {string} routesRoot Absolute path to `site/pages`.
+ * @returns {Route[]}
+ */
 export function discoverRoutes(routesRoot) {
   if (!fs.existsSync(routesRoot)) return [];
+  /** @type {Route[]} */
   const routes = [];
 
+  /** @param {string} dir */
   function walk(dir) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       if (isHiddenName(entry.name)) continue;
@@ -36,6 +50,12 @@ export function discoverRoutes(routesRoot) {
   return routes.sort((a, b) => a.route.localeCompare(b.route));
 }
 
+/**
+ * Derive a public route path from a source file path.
+ * @param {string} routesRoot Absolute path to `site/pages`.
+ * @param {string} file Absolute path to the source file.
+ * @returns {string}
+ */
 export function routeFromFile(routesRoot, file) {
   const ext = path.extname(file);
   const rel = path.relative(routesRoot, file).slice(0, -ext.length);
@@ -45,6 +65,12 @@ export function routeFromFile(routesRoot, file) {
   return route === "/" ? "/" : `${route}/`;
 }
 
+/**
+ * Map a public route to the `index.html` output path under `distRoot`.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} route Public route path.
+ * @returns {string}
+ */
 export function outputPathForRoute(distRoot, route) {
   const clean = route === "/" ? "" : route.replace(/^\/|\/$/g, "");
   return path.join(distRoot, clean, "index.html");

package/src/runtime.js

@@ -1,4 +1,18 @@
+/**
+ * Darkmown's tiny reactive runtime. Browser-only: it reads `data-wd-*` attributes
+ * emitted by the compiler, hydrates declared state, and re-renders on changes.
+ * @module runtime
+ */
+
+/**
+ * A reconciled loop-row element. Carries its source row on `__wdItem` so per-row
+ * button actions can resolve which row was clicked.
+ * @typedef {Element & { __wdItem?: any }} WdRow
+ */
+
+/** @type {Record<string, any>} */
 const state = {};
+/** @type {Set<string>} */
 const persistKeys = new Set();
 
 for (const script of document.querySelectorAll("script[data-wd-state]")) {
@@ -23,6 +37,12 @@ function savePersisted() {
   }
 }
 
+/**
+ * Safely read a dotted path off a value, rejecting prototype-pollution segments.
+ * @param {any} value
+ * @param {string | null} path
+ * @returns {any}
+ */
 function getPath(value, path) {
   if (!path) return value;
   let current = value;
@@ -35,23 +55,47 @@ function getPath(value, path) {
 }
 
 const computedDefs = [...document.querySelectorAll("[data-wd-computed]")].map((node) => ({
-  key: node.getAttribute("data-wd-computed-key"),
+  key: node.getAttribute("data-wd-computed-key") || "",
+  expr: node.getAttribute("data-wd-computed-expr") || "",
   evaluate: new Function("S", `return (${node.getAttribute("data-wd-computed-expr")});`)
 }));
 
+/**
+ * Log an expression failure when `window.wd.debug` is enabled.
+ * @param {string} expr
+ * @param {unknown} error
+ * @returns {void}
+ */
+function warn(expr, error) {
+  const wd = /** @type {any} */ (window).wd;
+  if (wd && wd.debug) console.warn(`[wd] expression failed: ${expr}`, error);
+}
+
+/**
+ * Re-evaluate all `:computed` definitions into `state`.
+ * @returns {void}
+ */
 function recompute() {
-  const read = (key, path) => getPath(state[key], path);
+  /** @param {string} key @param {string | null} [path] */
+  const read = (key, path) => getPath(state[key], path ?? null);
   for (const def of computedDefs) {
     try {
       state[def.key] = def.evaluate(read);
-    } catch {
+    } catch (error) {
       state[def.key] = undefined;
+      warn(def.expr, error);
     }
   }
 }
 
+/** @param {unknown} a @param {unknown} b @returns {boolean} */
 const containsFn = (a, b) => String(a ?? "").toLowerCase().includes(String(b ?? "").toLowerCase());
+/** @type {Map<string, Function>} */
 const predicateCache = new Map();
+/**
+ * @param {string} body
+ * @returns {Function}
+ */
 function loopPredicate(body) {
   let fn = predicateCache.get(body);
   if (!fn) {
@@ -61,6 +105,12 @@ function loopPredicate(body) {
   return fn;
 }
 
+/**
+ * Stable per-render key for a loop row, disambiguating duplicates with `#n`.
+ * @param {any} item
+ * @param {Map<string, number>} counts
+ * @returns {string}
+ */
 function loopKeyOf(item, counts) {
   const base =
     item && typeof item === "object"
@@ -71,13 +121,20 @@ function loopKeyOf(item, counts) {
   return seen ? `${base}#${seen}` : base;
 }
 
+/**
+ * Fill a cloned loop row node: resolve per-item `:if` regions and text binds.
+ * @param {Element} node
+ * @param {any} item
+ * @returns {void}
+ */
 function fillItem(node, item) {
   // querySelectorAll does not descend into <template> content, so this only sees
   // the outermost regions; recursing into each injected branch fills the rest.
   for (const region of node.querySelectorAll("[data-wd-each-if]")) {
     const value = getPath(item, region.getAttribute("data-wd-path"));
     const output = region.querySelector("[data-wd-each-if-out]");
-    const template = region.querySelector(value ? "template[data-wd-if-true]" : "template[data-wd-if-false]");
+    if (!output) continue;
+    const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector(value ? "template[data-wd-if-true]" : "template[data-wd-if-false]"));
     output.innerHTML = template?.innerHTML || "";
     fillItem(output, item);
   }
@@ -89,15 +146,21 @@ function fillItem(node, item) {
   }
 }
 
-function render() {
+/**
+ * Synchronously render the whole document from current `state`:
+ * computed → if-regions → keyed loop reconcile → text/input binds.
+ * @returns {void}
+ */
+function renderNow() {
   recompute();
   for (const node of document.querySelectorAll("[data-wd-if]")) {
-    const value = getPath(state[node.getAttribute("data-wd-if")], node.getAttribute("data-wd-path"));
+    const value = getPath(state[node.getAttribute("data-wd-if") || ""], node.getAttribute("data-wd-path"));
     const active = String(Boolean(value));
     if (node.getAttribute("data-wd-if-active") === active) continue;
     node.setAttribute("data-wd-if-active", active);
     const output = node.querySelector("[data-wd-if-out]");
-    const template = node.querySelector(value ? "template[data-wd-true]" : "template[data-wd-false]");
+    if (!output) continue;
+    const template = /** @type {HTMLTemplateElement | null} */ (node.querySelector(value ? "template[data-wd-true]" : "template[data-wd-false]"));
     output.innerHTML = template?.innerHTML || "";
   }
 
@@ -105,29 +168,38 @@ function render() {
     const key = region.getAttribute("data-wd-loop");
     const data = region.getAttribute("data-wd-loop-data");
     const rows = key ? state[key] : (data ? JSON.parse(data) : []);
-    const template = region.querySelector("template[data-wd-loop-template]");
+    const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-template]"));
     const out = region.querySelector("[data-wd-loop-out]");
     if (!template || !out) continue;
     let list = Array.isArray(rows) ? rows : [];
     const where = region.getAttribute("data-wd-loop-where");
     if (where) {
       const predicate = loopPredicate(where);
-      list = list.filter((item) =>
-        predicate((path) => getPath(item, path), (k, r) => getPath(state[k], r || ""), containsFn)
-      );
+      list = list.filter((/** @type {any} */ item) => {
+        try {
+          return predicate((/** @type {string | null} */ path) => getPath(item, path), (/** @type {string} */ k, /** @type {string} */ r) => getPath(state[k], r || ""), containsFn);
+        } catch (error) {
+          warn(where, error);
+          return false;
+        }
+      });
     }
 
+    /** @type {Map<string, WdRow>} */
     const existing = new Map();
     for (const child of [...out.children]) {
-      existing.set(child.getAttribute("data-wd-loop-key"), child);
+      existing.set(child.getAttribute("data-wd-loop-key") || "", /** @type {WdRow} */ (child));
     }
+    /** @type {Map<string, number>} */
     const counts = new Map();
+    /** @type {Set<string>} */
     const used = new Set();
     for (const item of list) {
       const key = loopKeyOf(item, counts);
       let node = existing.get(key);
       if (!node || used.has(key)) {
-        node = template.content.firstElementChild.cloneNode(true);
+        node = /** @type {WdRow} */ (template.content.firstElementChild?.cloneNode(true));
+        if (!node) continue;
         node.setAttribute("data-wd-loop-key", key);
       }
       used.add(key);
@@ -141,35 +213,53 @@ function render() {
   }
 
   for (const node of document.querySelectorAll("[data-wd-bind]")) {
-    node.textContent = getPath(state[node.getAttribute("data-wd-bind")], node.getAttribute("data-wd-path")) ?? "";
+    node.textContent = getPath(state[node.getAttribute("data-wd-bind") || ""], node.getAttribute("data-wd-path")) ?? "";
   }
 
   for (const input of document.querySelectorAll("[data-wd-bind-input]")) {
-    if (document.activeElement !== input) input.value = state[input.getAttribute("data-wd-bind-input")] ?? "";
+    if (document.activeElement !== input) /** @type {HTMLInputElement} */ (input).value = state[input.getAttribute("data-wd-bind-input") || ""] ?? "";
   }
 }
 
+// Coalesce rapid state mutations into one render on the next tick. Each scheduled
+// pass always reads the latest state, so the final update is never dropped.
+const schedule = typeof requestAnimationFrame === "function" ? requestAnimationFrame : queueMicrotask;
+let scheduled = false;
+function render() {
+  if (scheduled) return;
+  scheduled = true;
+  schedule(() => {
+    scheduled = false;
+    renderNow();
+  });
+}
+
 document.addEventListener("input", (event) => {
-  const input = event.target.closest("[data-wd-bind-input]");
+  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;
+  state[input.getAttribute("data-wd-bind-input") || ""] = input.value;
   savePersisted();
   render();
 });
 
 // The clicked button's row: the nearest reconciled loop node carries its item.
+/**
+ * Resolve the loop source and row item for a clicked element, if inside a loop.
+ * @param {Element} el
+ * @returns {{ srcKey: string | null, item: any } | null}
+ */
 function clickedRow(el) {
-  const row = el.closest("[data-wd-loop-key]");
+  const row = /** @type {WdRow | null} */ (el.closest("[data-wd-loop-key]"));
   const region = el.closest("[data-wd-loop]");
   if (!row || !region) return null;
   return { srcKey: region.getAttribute("data-wd-loop"), item: row.__wdItem };
 }
 
 document.addEventListener("click", (event) => {
-  const action = event.target.closest("[data-wd-action]");
+  const action = /** @type {Element} */ (event.target)?.closest("[data-wd-action]");
   if (!action) return;
   const op = action.getAttribute("data-wd-action");
-  const target = action.getAttribute("data-wd-target");
+  const target = action.getAttribute("data-wd-target") || "";
   const rawValue = action.getAttribute("data-wd-value");
   const value = rawValue === null ? undefined : JSON.parse(rawValue);
 
@@ -180,7 +270,7 @@ document.addEventListener("click", (event) => {
   if (op === "set") state[target] = value;
   if (op === "remove") {
     const row = clickedRow(action);
-    if (row && row.srcKey) state[row.srcKey] = (Array.isArray(state[row.srcKey]) ? state[row.srcKey] : []).filter((x) => x !== row.item);
+    if (row && row.srcKey) state[row.srcKey] = (Array.isArray(state[row.srcKey]) ? state[row.srcKey] : []).filter((/** @type {any} */ x) => x !== row.item);
   }
   if (op === "append-row") {
     const row = clickedRow(action);
@@ -197,10 +287,10 @@ document.addEventListener("click", (event) => {
 });
 
 document.addEventListener("submit", (event) => {
-  const form = event.target.closest("[data-wd-form]");
+  const form = /** @type {HTMLFormElement | null} */ (/** @type {Element} */ (event.target)?.closest("[data-wd-form]"));
   if (!form) return;
   event.preventDefault();
-  const key = form.getAttribute("data-wd-form");
+  const key = form.getAttribute("data-wd-form") || "";
   const action = form.getAttribute("action");
 
   if (!action) {
@@ -213,7 +303,7 @@ document.addEventListener("submit", (event) => {
   fetch(action, {
     method: form.getAttribute("method") || "post",
     headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams(new FormData(form)).toString()
+    body: new URLSearchParams(/** @type {any} */ (new FormData(form))).toString()
   })
     .then(async (response) => {
       const text = await response.text();
@@ -235,9 +325,14 @@ document.addEventListener("submit", (event) => {
     });
 });
 
+/**
+ * Kick off a `:fetch` request and write the result (or error) into state.
+ * @param {Element} node
+ * @returns {void}
+ */
 function startFetch(node) {
-  const key = node.getAttribute("data-wd-fetch-key");
-  fetch(node.getAttribute("data-wd-fetch-url"))
+  const key = node.getAttribute("data-wd-fetch-key") || "";
+  fetch(node.getAttribute("data-wd-fetch-url") || "")
     .then((response) => {
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
       return response.json();
@@ -266,15 +361,20 @@ for (const node of document.querySelectorAll("[data-wd-fetch]")) {
   }
 }
 
-window.wd = {
+// Public escape hatch on `window.wd`. Set `window.wd.debug = true` to log failing
+// computed/where expressions to the console.
+/** @type {any} */ (window).wd = {
   state,
+  debug: false,
+  /** @param {string} key */
   get: (key) => state[key],
+  /** @param {string} key @param {any} value */
   set: (key, value) => {
     state[key] = value;
     savePersisted();
     render();
   },
-  render
+  render: renderNow
 };
 
-render();
+renderNow();

package/src/scaffold.js

@@ -5,6 +5,11 @@ 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.
+ * @param {string} root Absolute path to the target project directory.
+ * @returns {{ root: string }}
+ */
 export function initProject(root) {
   fs.mkdirSync(root, { recursive: true });
   writeNew(root, "package.json", JSON.stringify({
@@ -128,6 +133,13 @@ export function initProject(root) {
   return { root };
 }
 
+/**
+ * Write a file relative to `root` only if it does not already exist.
+ * @param {string} root Project root directory.
+ * @param {string} file Path relative to `root`.
+ * @param {string} content File contents (a trailing newline is added).
+ * @returns {void}
+ */
 function writeNew(root, file, content) {
   const target = path.join(root, file);
   if (fs.existsSync(target)) return;

package/src/skin.js

@@ -8,11 +8,29 @@ const aliases = new Map([
 // `font` is aliased to font-family for the common `font <stack>` case, but the
 // real CSS `font` shorthand (`font 16px/1.4 system-ui`) must pass through. If
 // the value looks like a shorthand (leads with a size or contains `/`), keep it.
+/**
+ * @param {string} prop
+ * @param {string[]} rest
+ * @returns {string}
+ */
 function resolveProp(prop, rest) {
   if (prop === "font" && (/^[\d.]/.test(rest[0] || "") || rest.join(" ").includes("/"))) return "font";
   return aliases.get(prop) || prop;
 }
 
+/**
+ * A nesting frame in the indentation stack.
+ * @typedef {object} SkinFrame
+ * @property {number} indent
+ * @property {string | null} selector
+ * @property {string} [media]
+ */
+
+/**
+ * Compile indentation-based `.skin` source into CSS.
+ * @param {string} source
+ * @returns {string}
+ */
 export function compileSkin(source) {
   const lines = source
     .replace(/\r\n?/g, "\n")
@@ -26,11 +44,15 @@ export function compileSkin(source) {
       // 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() }));
+    .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
 
+  /** @type {SkinFrame[]} */
   const stack = [];
+  /** @type {string[]} */
   const css = [];
+  /** @type {number | null} */
   let tokenIndent = null;
+  /** @type {string[]} */
   const rootVars = [];
 
   for (let i = 0; i < lines.length; i++) {
@@ -51,7 +73,7 @@ export function compileSkin(source) {
     }
 
     if (tokenIndent !== null && indent <= tokenIndent) tokenIndent = null;
-    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
+    while (stack.length && (stack.at(-1)?.indent ?? -1) >= indent) stack.pop();
 
     if (opensBlock) {
       const parent = stack.at(-1)?.selector;
@@ -78,12 +100,18 @@ export function compileSkin(source) {
   return css.join("\n");
 }
 
+/**
+ * Combine a selector with its parent (handles `&` nesting and comma lists).
+ * @param {string} text
+ * @param {string | null | undefined} parent
+ * @returns {string}
+ */
 function normalizeSelector(text, parent) {
   const selector = text === "page" ? "body" : text;
   if (!parent || parent === ":root") return selector;
   return selector
     .split(",")
-    .map((part) => {
+    .map((/** @type {string} */ part) => {
       const clean = part.trim();
       return clean.startsWith("&") ? clean.replace("&", parent) : `${parent} ${clean}`;
     })

package/src/statics.js

@@ -1,6 +1,14 @@
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 
+/**
+ * Serve a built file for a request URL out of `distRoot`, or a 404 page.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} url Request URL (may include a query string).
+ * @param {http.ServerResponse} res Response to write to.
+ * @returns {void}
+ */
 export function serve(distRoot, url, res) {
   const file = resolvePublicFile(distRoot, url || "/");
   if (!file || !fs.existsSync(file)) {
@@ -12,6 +20,13 @@ export function serve(distRoot, url, res) {
   fs.createReadStream(file).pipe(res);
 }
 
+/**
+ * Resolve a request URL to an absolute file inside `distRoot`, guarding against
+ * path traversal. Returns null when the resolved path escapes the root.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} url Request URL (may include a query string).
+ * @returns {string | null}
+ */
 export function resolvePublicFile(distRoot, url) {
   const cleanUrl = decodeURIComponent(url.split("?")[0]);
   const base = cleanUrl.startsWith("/__wd/")
@@ -23,6 +38,11 @@ export function resolvePublicFile(distRoot, url) {
   return requested;
 }
 
+/**
+ * Map a file path to a response content-type, defaulting to `text/html`.
+ * @param {string} file File path or name.
+ * @returns {string}
+ */
 export function contentType(file) {
   if (file.endsWith(".css")) return "text/css";
   if (file.endsWith(".js")) return "text/javascript";

package/types/builder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ */
+export function buildSite(cwd?: string): {
+    routes: RouteManifestEntry[];
+    distRoot: string;
+};
+/**
+ * Strip JSDoc `/** ... *\/` blocks from the runtime before it ships.
+ * The source keeps full type annotations (for `checkJs` + `.d.ts`), but the
+ * browser never needs to download them — this keeps the shipped runtime lean
+ * and the gzip budget honest (measured against what users actually receive).
+ * Only `/** ... *\/` blocks are removed; code and string literals are untouched.
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripRuntimeComments(source: string): string;
+export type Paths = import("./config.js").Paths;
+export type Assets = import("./compiler.js").Assets;
+/**
+ * A built route entry written to `dist/routes.json`.
+ */
+export type RouteManifestEntry = {
+    /**
+     * Public route path.
+     */
+    route: string;
+    /**
+     * Source file path, relative to cwd, POSIX-separated.
+     */
+    file: string;
+    assets: {
+        skins: string[];
+        scripts: string[];
+        runtime: boolean;
+    };
+};