@zvndev/darkmown 0.19.0 → 1.0.0

package/src/compiler/markdown.js

@@ -0,0 +1,242 @@
+// ---------------------------------------------------------------------------
+// Markdown layer: the shared markdown-it instances (raw-HTML default + a lazy
+// `html: false` strict variant), the `wd_binding` inline plugin and `wd_attrs`
+// core plugin, and prose rendering with `{ name.path }` interpolation resolved
+// against the loop item / static scope / declared state.
+// ---------------------------------------------------------------------------
+
+import MarkdownIt from "markdown-it";
+import { LOOP_META } from "./context.js";
+import { applyPipeline, fmtAttr, validatePipes } from "./format.js";
+import {
+  escapeHtml,
+  getPath,
+  interpolateLeaf,
+  lookupVar,
+  resolveStateKey
+} from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+const md = new MarkdownIt({ html: true });
+md.use(bindingPlugin);
+md.use(attrsPlugin);
+
+// Raw HTML in markdown passes through by default (a documented design choice).
+// Pages can opt out with frontmatter `html: false` for untrusted content; the
+// stricter instance is built lazily so the default path stays a single instance.
+/** @type {MarkdownIt | null} */
+let mdNoHtml = null;
+/**
+ * Pick the markdown-it instance for a page (raw HTML on by default, off with `html: false`).
+ * @param {Meta} [meta]
+ * @returns {MarkdownIt}
+ */
+export function selectMd(meta) {
+  // Frontmatter scalars stay strings (no coercion), so accept both forms.
+  if (meta?.html !== false && meta?.html !== "false") return md;
+  if (!mdNoHtml) {
+    mdNoHtml = new MarkdownIt({ html: false });
+    mdNoHtml.use(bindingPlugin);
+    mdNoHtml.use(attrsPlugin);
+  }
+  return mdNoHtml;
+}
+
+/**
+ * @param {string} text
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function renderProse(text, ctx) {
+  text = resolveDestinationBindings(text, ctx);
+  return (ctx.md ?? md).render(text, {
+    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx)
+  });
+}
+
+/**
+ * Pre-resolve `{ expr }` interpolations sitting in a markdown link/image
+ * destination — the `](…)` slot — so a build-time `@loop` (or any static scope)
+ * can drive an href/src. A markdown destination cannot contain the spaces inside
+ * `{ … }`, so markdown-it would otherwise never form the link; substituting the
+ * static value here lets the normal link/image parser run. Only build-time
+ * (static-scope) values are substituted — reactive `:state`/reactive-loop
+ * bindings resolve to `null` and are left untouched (they cannot live in a
+ * destination). Issue #19.
+ * @param {string} text
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function resolveDestinationBindings(text, ctx) {
+  return text.replace(
+    /(\]\(\s*)\{\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\}/g,
+    (whole, prefix, expr) => {
+      const raw = resolveBindingRaw(expr, ctx);
+      return raw == null ? whole : prefix + raw;
+    }
+  );
+}
+
+/**
+ * Resolve `{ expr }` to its raw static value (a plain string) for use in a
+ * destination, or `null` when the binding is reactive or not in build-time
+ * scope. Mirrors the static branch of {@link resolveBindingHtml} but returns the
+ * unescaped value (markdown-it normalizes the URL).
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {string | null}
+ */
+function resolveBindingRaw(expr, ctx) {
+  const segs = expr.split(".");
+  const found = lookupVar(ctx.scope, segs[0]);
+  if (!found.found) return null;
+  const resolved = getPath(found.value, segs.slice(1));
+  const leaf = interpolateLeaf(resolved, expr, ctx);
+  return leaf == null ? null : String(leaf);
+}
+
+/**
+ * markdown-it plugin: turns `{ name.path }` into an inline `html_inline` token
+ * whose content comes from the env's `resolveBinding` callback.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function bindingPlugin(mdInstance) {
+  mdInstance.inline.ruler.push("wd_binding", (state, silent) => {
+    if (state.src.charCodeAt(state.pos) !== 0x7b /* { */) return false;
+    // Capture the path plus an optional `| formatter:arg | …` pipe chain. Pipe
+    // arguments may not contain `}` (they may be quoted), so the chain runs to
+    // the first closing brace.
+    const match = /^\{\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\s*(?:\|[^}]*)?)\}/.exec(
+      state.src.slice(state.pos)
+    );
+    if (!match) return false;
+    const resolve = state.env?.resolveBinding;
+    const html = resolve ? resolve(match[1].trim()) : null;
+    if (typeof html !== "string") return false;
+    if (!silent) {
+      const token = state.push("html_inline", "", 0);
+      token.content = html;
+    }
+    state.pos += match[0].length;
+    return true;
+  });
+}
+
+/**
+ * markdown-it plugin (core rule): a `{.class .class #id}` block immediately
+ * following an inline element (link, image, em/strong, code) attaches those
+ * classes / id to that element. Lets a link be styled as a button without a
+ * wrapper container. The block must directly follow the element (no space), and
+ * `{ … }` interpolation is unaffected (its content starts with a name, not `.`/`#`).
+ * Issue #18.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function attrsPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_attrs", (state) => {
+    for (const block of state.tokens) {
+      if (block.type !== "inline" || !block.children) continue;
+      const children = block.children;
+      for (let i = 0; i < children.length; i++) {
+        const tok = children[i];
+        if (tok.type !== "text") continue;
+        const m = /^\{([.#][^}]*)\}/.exec(tok.content);
+        if (!m) continue;
+        const target = attrTarget(children, i);
+        if (!target) continue;
+        for (const part of m[1].split(/\s+/).filter(Boolean)) {
+          if (part[0] === ".") target.attrJoin("class", part.slice(1));
+          else if (part[0] === "#") target.attrSet("id", part.slice(1));
+        }
+        tok.content = tok.content.slice(m[0].length);
+      }
+    }
+    return false;
+  });
+}
+
+/**
+ * The inline token an attr block attaches to: the immediately-preceding image
+ * (self-closing) or the open token matching the immediately-preceding close
+ * (link/em/strong/…). Returns null when nothing valid precedes. Exported so its
+ * contract — including the defensive unbalanced-close fallback that markdown-it's
+ * always-balanced token stream never triggers in practice — is unit-testable.
+ * @param {any[]} children markdown-it inline child tokens
+ * @param {number} i Index of the attr-block text token.
+ * @returns {any} the matching markdown-it Token, or null
+ */
+export function attrTarget(children, i) {
+  const prev = children[i - 1];
+  if (!prev) return null;
+  if (prev.type === "image") return prev;
+  // Not a close token (e.g. text, softbreak, or an open) → nothing to attach to.
+  if (prev.nesting !== -1) return null;
+  // Walk back to the matching open, counting nested same-type close/open pairs.
+  const openType = prev.type.replace(/_close$/, "_open");
+  let depth = 0;
+  for (let j = i - 1; j >= 0; j--) {
+    const t = children[j];
+    if (t.type === prev.type) depth++;
+    else if (t.type === openType) {
+      depth--;
+      if (depth === 0) return t;
+    }
+  }
+  // Unbalanced close with no matching open — markdown-it never emits this, but
+  // the guard keeps attrTarget total: no element is attached.
+  return null;
+}
+
+/**
+ * Resolve a `{ name.path }` binding to HTML: loop item span, static value, or
+ * a reactive bind span. Returns null when nothing in scope matches.
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {string | null}
+ */
+function resolveBindingHtml(expr, ctx) {
+  const { path, stages } = validatePipes(expr, ctx);
+  const segs = path.split(".");
+  const head = segs[0];
+  // Reactive nodes carry the pipe chain in data-wd-fmt; static values fold now.
+  const fmt = stages.length ? ` data-wd-fmt="${escapeHtml(fmtAttr(stages))}"` : "";
+  /** @param {unknown} v */
+  const fold = (v) => (stages.length ? applyPipeline(v, stages) : v);
+
+  // Per-row meta vars ($index/$number/$first/$last/$count) — only inside a loop.
+  if (LOOP_META[head]) {
+    if (!ctx.loopMeta)
+      throw new Error(
+        `"{ ${expr} }" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Move it into a loop body, or rename your value.`
+      );
+    if (ctx.loopItem) return `<span data-wd-each-meta="${LOOP_META[head]}"${fmt}></span>`; // reactive: filled per row
+    // static: the value is in scope (injected by staticUnroll); fall through.
+  }
+
+  if (ctx.loopItem && head === ctx.loopItem) {
+    const rest = segs.slice(1).join(".");
+    return `<span data-wd-each${rest ? ` data-wd-path="${escapeHtml(rest)}"` : ""}${fmt}></span>`;
+  }
+
+  const staticValue = lookupVar(ctx.scope, head);
+  if (staticValue.found) {
+    const resolved = getPath(staticValue.value, segs.slice(1));
+    return escapeHtml(interpolateLeaf(fold(resolved), expr, ctx));
+  }
+
+  const key = resolveStateKey(head, ctx);
+  if (key) {
+    ctx.comp.assets.runtime = true;
+    const initial = getPath(ctx.comp.state.get(key), segs.slice(1));
+    const rest = segs.slice(1).join(".");
+    const pathAttr = rest ? ` data-wd-path="${escapeHtml(rest)}"` : "";
+    return `<span data-wd-bind="${key}"${pathAttr}${fmt}>${escapeHtml(interpolateLeaf(fold(initial), expr, ctx))}</span>`;
+  }
+
+  return null;
+}

package/src/compiler/page.js

@@ -0,0 +1,267 @@
+// ---------------------------------------------------------------------------
+// Page shell + document assembly: wrap a compiled body in the full HTML shell
+// (title, social meta, favicon, skins, scripts, optional view transitions +
+// speculationrules), harden every `<img>` at compile time, and drive the
+// per-file compile (frontmatter + colocated assets + body / `.md` passthrough).
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { imageSize } from "image-size";
+import { compileBody } from "./body.js";
+import { createCompilation, createScope } from "./context.js";
+import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
+import { collectColocatedAssets, scanMarkdownHints } from "./includes.js";
+import { escapeHtml } from "./interpolation.js";
+import { selectMd } from "./markdown.js";
+
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("./context.js").Scope} Scope
+ * @typedef {import("./context.js").Compilation} Compilation
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").CompiledDocument} CompiledDocument
+ * @typedef {import("./context.js").CompiledPage} CompiledPage
+ */
+
+/**
+ * Compile a page source file into a full HTML document plus its assets.
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {Paths} context Resolved project paths.
+ * @returns {CompiledPage}
+ */
+export function compilePage(file, context) {
+  const compiled = compileDocument(file, context);
+  const title = compiled.meta.title || "Darkmown";
+  const description = compiled.meta.description || "";
+  // Optional `image:` frontmatter sets the social-share preview (absolute URL).
+  const image = typeof compiled.meta.image === "string" ? compiled.meta.image : "";
+  /** @type {string[]} */
+  const social = [];
+  if (description) social.push(`<meta name="description" content="${escapeHtml(description)}">`);
+  if (description || image) {
+    social.push(`<meta property="og:title" content="${escapeHtml(title)}">`);
+    if (description)
+      social.push(`<meta property="og:description" content="${escapeHtml(description)}">`);
+    social.push(`<meta property="og:type" content="website">`);
+  }
+  if (image) {
+    social.push(`<meta property="og:image" content="${escapeHtml(image)}">`);
+    social.push(`<meta name="twitter:image" content="${escapeHtml(image)}">`);
+  }
+  if (description || image) {
+    social.push(
+      `<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}">`
+    );
+  }
+  const descriptionTag = social.length ? `\n  ${social.join("\n  ")}` : "";
+  const favicon =
+    "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2032%2032'%3E%3Crect%20width='32'%20height='32'%20rx='6'%20fill='%2318221d'/%3E%3Ctext%20x='16'%20y='23'%20text-anchor='middle'%20font-family='Georgia,serif'%20font-size='19'%20font-weight='bold'%20fill='%23f7f3ea'%3ED%3C/text%3E%3C/svg%3E";
+  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];
+  const scripts = scriptSrcs
+    .map((src) => `<script type="module" src="${src}"></script>`)
+    .join("\n");
+  // Cross-document view transitions: opt in per page with `transitions: true` in
+  // frontmatter to emit a CSS-only stylesheet — a smooth same-origin transition
+  // on navigation, with zero JavaScript. Ignored by browsers without support
+  // (graceful, transition-free fallback) and only applies to same-origin
+  // navigations where both the outgoing and incoming page opt in.
+  //
+  // The default UA animation cross-fades the root: outgoing opacity 1→0 while
+  // incoming 0→1, both at once. Mid-navigation that leaves the two pages
+  // superimposed at ~50% opacity — headings ghost over headings. We override it
+  // with a directional fade+slide (old lifts up and out, new rises up and in) so
+  // the pages move past each other instead of stacking. Short + eased = peppy.
+  const wantTransitions =
+    compiled.meta.transitions === true || compiled.meta.transitions === "true";
+  const transitions = wantTransitions
+    ? `\n  <style>
+    @view-transition { navigation: auto; }
+    ::view-transition-old(root) { animation: wd-nav-out 200ms cubic-bezier(0.4, 0, 1, 1) both; }
+    ::view-transition-new(root) { animation: wd-nav-in 200ms cubic-bezier(0, 0, 0.2, 1) both; }
+    @keyframes wd-nav-out { to { opacity: 0; transform: translateY(-1rem); } }
+    @keyframes wd-nav-in { from { opacity: 0; transform: translateY(1rem); } }
+    @media (prefers-reduced-motion: reduce) {
+      ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 1ms; }
+      @keyframes wd-nav-out { to { opacity: 0; } }
+      @keyframes wd-nav-in { from { opacity: 0; } }
+    }
+  </style>`
+    : "";
+
+  // The latency half of smooth navigation — and what kills the white flash. A
+  // declarative speculationrules script (the browser interprets it — not
+  // framework runtime JS, so the zero-JS invariant holds) *prerenders* the next
+  // same-origin page on hover/pointerdown. Prefetch only warms the cache, so the
+  // page still has to render on click — that render gap is the white flash. A
+  // prerender renders the whole page in a hidden tab ahead of the click, so
+  // activation is instant: no render gap, and the view transition fires on the
+  // already-painted page. Safe now that pages are light. Eagerness `moderate` =
+  // ~200ms hover / pointerdown, capped at two. Mark a link `{.no-prefetch}` to
+  // opt it out; `rel=nofollow` links are never speculated. Browsers without
+  // support (or with preloading disabled) ignore the tag and navigate normally.
+  const speculation = wantTransitions
+    ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
+    : "";
+
+  const body = enhanceImages(compiled.html, context);
+
+  return {
+    meta: compiled.meta,
+    html: `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>${descriptionTag}
+  <link rel="icon" href="${favicon}">
+  ${cssLinks}${transitions}${speculation}
+</head>
+<body>
+${body}
+${scripts}
+</body>
+</html>`,
+    assets: compiled.assets,
+    warnings: compiled.warnings
+  };
+}
+
+/**
+ * Harden every `<img>` in the assembled page body — compile-time only, zero
+ * runtime JS. Bare markdown images reflow the page as they decode (cumulative
+ * layout shift — the literal "jump" on navigation) and load eagerly. This
+ * stamps intrinsic `width`/`height` (read from the file on disk so the browser
+ * reserves space), `decoding="async"` on all, and a load-priority split: the
+ * first image is the LCP candidate (eager + `fetchpriority="high"`), the rest
+ * lazy-load. Author-set attributes are never overwritten.
+ * @param {string} html Assembled page body HTML.
+ * @param {Paths} paths Resolved project paths.
+ * @returns {string}
+ */
+export function enhanceImages(html, paths) {
+  let index = 0;
+  return html.replace(/<img\b[^>]*?\/?>/g, (tag) => {
+    const i = index++;
+    const has = (/** @type {string} */ attr) => new RegExp(`\\b${attr}\\s*=`, "i").test(tag);
+    /** @type {string[]} */
+    const add = [];
+    // Dimensions only when the author hasn't sized it — adding one axis to a
+    // manually-sized image would distort its aspect ratio.
+    if (!has("width") && !has("height")) {
+      const dim = measureImage(srcOf(tag), paths);
+      if (dim) add.push(`width="${dim.width}"`, `height="${dim.height}"`);
+    }
+    if (!has("decoding")) add.push(`decoding="async"`);
+    if (i === 0) {
+      // First image is the LCP candidate: stays eager, gets a priority hint.
+      if (!has("fetchpriority")) add.push(`fetchpriority="high"`);
+    } else if (!has("loading")) {
+      add.push(`loading="lazy"`);
+    }
+    if (!add.length) return tag;
+    return `${tag.replace(/\s*\/?>\s*$/, "")} ${add.join(" ")}>`;
+  });
+}
+
+/**
+ * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
+ * @param {string} tag
+ * @returns {string}
+ */
+function srcOf(tag) {
+  const m = tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i);
+  return m ? m[1] : "";
+}
+
+/**
+ * Read an image's intrinsic dimensions from disk, or null when the src is
+ * remote/relative/unreadable. Resolution mirrors the asset emit: `/__wd/media/x`
+ * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
+ * @param {string} src
+ * @param {Paths} paths
+ * @returns {{ width: number, height: number } | null}
+ */
+function measureImage(src, paths) {
+  if (!src || /^(https?:)?\/\//i.test(src) || src.startsWith("data:")) return null;
+  let filePath;
+  if (src.startsWith("/__wd/media/")) {
+    filePath = path.join(paths.shelfRoot, src.slice("/__wd/media/".length));
+  } else if (src.startsWith("/")) {
+    filePath = path.join(paths.routesRoot, src.slice(1));
+  } else {
+    return null; // page-relative: the source directory is lost after assembly
+  }
+  try {
+    const { width, height } = imageSize(fs.readFileSync(filePath));
+    if (typeof width === "number" && typeof height === "number") return { width, height };
+  } catch {
+    /* missing or unreadable — degrade to no dimensions */
+  }
+  return null;
+}
+
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
+ * @param {string} file Absolute path to the source file.
+ * @param {Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file, context, stack = [], vars = {}) {
+  const comp = createCompilation();
+  const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
+  return { meta: result.meta, html: result.html, assets: comp.assets, warnings: comp.warnings };
+}
+
+/**
+ * Compile a single file: parse frontmatter, collect assets, render body.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {string[]} stack
+ * @param {Scope} scope
+ * @param {Compilation} comp
+ * @param {string[]} sections
+ * @param {string | null} loopItem
+ * @returns {{ meta: Meta, html: string }}
+ */
+export function compileFile(file, context, stack, scope, comp, sections, loopItem) {
+  const real = fs.realpathSync(file);
+  if (stack.includes(real)) {
+    throw new Error(
+      `Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`
+    );
+  }
+
+  const raw = fs.readFileSync(file, "utf8");
+  const { meta, body } = parseFrontmatter(raw, file);
+  warnLikelyFrontmatter(raw, file, comp);
+  collectColocatedAssets(file, context, comp.assets);
+
+  if (path.extname(file) === ".md") {
+    scanMarkdownHints(body, file, comp);
+    return { meta, html: selectMd(meta).render(body, {}) };
+  }
+
+  // Expose this file's frontmatter to the body under `meta` so `{ meta.title }`,
+  // `{ meta.tags }`, and `@loop meta.tags into tag` resolve as static values.
+  /** @type {Ctx} */
+  const ctx = {
+    file,
+    context,
+    stack: [...stack, real],
+    scope: createScope(scope, { meta }),
+    comp,
+    sections,
+    loopItem,
+    md: selectMd(meta)
+  };
+  return { meta, html: compileBody(body.replace(/\r\n?/g, "\n").split("\n"), ctx) };
+}