@zvndev/darkmown 2.2.0 → 2.3.1-next.1.g3a4a8dc

package/types/src/feeds.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @typedef {import("./router.js").Route} Route
+ */
+/**
+ * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
+ * ready for a sitemap `<lastmod>`.
+ * @typedef {object} DatedRoute
+ * @property {string} loc Absolute URL (`site_url` + route path).
+ * @property {string} lastmod ISO date (`yyyy-mm-dd`).
+ */
+/**
+ * XML-escape a text value for use inside an element or attribute. Covers the
+ * five predefined XML entities — the same set RSS/sitemap consumers expect.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeXml(value: string): string;
+/**
+ * Join the site origin and a route path into one absolute URL, collapsing the
+ * boundary slash so `https://x.com` + `/about/` → `https://x.com/about/` (the
+ * home route `/` → `https://x.com/`). `siteUrl` is expected without a trailing
+ * slash (the documented contract); a stray one is tolerated.
+ * @param {string} siteUrl Absolute origin, e.g. `https://example.com`.
+ * @param {string} route Route path (always trailing-slashed, e.g. `/about/`).
+ * @returns {string}
+ */
+export function absoluteUrl(siteUrl: string, route: string): string;
+/**
+ * The last-modified date for a source file, as an ISO `yyyy-mm-dd` string.
+ * Resolution order: the file's frontmatter `date:` is handled by the caller
+ * (it wins); this helper covers the fallback chain — the git last-commit date
+ * of the file, else the filesystem mtime. Git is wrapped in try/catch so a
+ * scaffolded app or an extracted tarball (no `.git`) degrades to mtime instead
+ * of crashing the build.
+ * @param {string} file Absolute path to the source file.
+ * @returns {string} ISO date (`yyyy-mm-dd`).
+ */
+export function lastmodFor(file: string): string;
+/**
+ * Format a `Date` as an ISO `yyyy-mm-dd` string (sitemap `<lastmod>` form).
+ * @param {Date} date
+ * @returns {string}
+ */
+export function isoDate(date: Date): string;
+/**
+ * Format a frontmatter `date:` value as an RFC-822 date for an RSS `<pubDate>`
+ * (e.g. `Sat, 28 Jun 2026 00:00:00 GMT`). Accepts anything `new Date` parses
+ * (an ISO `yyyy-mm-dd`, a full timestamp); an unparseable value returns "" so
+ * the caller can omit the element rather than emit `Invalid Date`.
+ * @param {string} value Raw frontmatter date string.
+ * @returns {string} RFC-822 date in GMT, or "" when unparseable.
+ */
+export function rfc822(value: string): string;
+/**
+ * Extract the first paragraph of a plain-`.md` body as a single-line snippet —
+ * the RSS description fallback when a `.md` post has neither `excerpt:` nor
+ * `description:`. Deliberately dumb: skip leading blank/frontmatter-less lines,
+ * take the first run of non-blank prose, strip the most common inline markdown
+ * (heading marks, emphasis, inline-code, links → their text), and collapse
+ * whitespace. Returns "" when the body is empty or starts with a non-prose
+ * block (a fence/heading-only doc) — the caller then falls back further.
+ * @param {string} body The post-frontmatter markdown body.
+ * @returns {string}
+ */
+export function firstParagraph(body: string): string;
+/**
+ * The RSS `<description>` for a post: explicit `excerpt:` wins, else the source
+ * `description:`, else (plain `.md` only) the first rendered paragraph. `.wd`
+ * bodies are NOT scanned for a first paragraph — stripping reactive/directive
+ * markup back to clean prose is not worth the fragility, so a `.wd` post without
+ * `excerpt`/`description` simply gets no description.
+ * @param {import("./compiler.js").Meta} meta
+ * @param {string} file Absolute source path (its extension gates `.md` scanning).
+ * @param {string} body The post-frontmatter body.
+ * @returns {string}
+ */
+export function rssDescription(meta: import("./compiler.js").Meta, file: string, body: string): string;
+/**
+ * Build `sitemap.xml` from the emitted (post-draft-filter) routes. One `<url>`
+ * per route — reactive pages included (they're indexable HTML) — with `<loc>` =
+ * `site_url` + path and `<lastmod>` from the supplied date. The `/404/` route is
+ * excluded by the caller before this point. No `<priority>`/`<changefreq>` —
+ * Google ignores them and they invite bit-rot.
+ * @param {DatedRoute[]} entries Absolute loc + ISO lastmod, in route order.
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildSitemap(entries: DatedRoute[]): string;
+/**
+ * An RSS item — a dated post in feed order.
+ * @typedef {object} RssItem
+ * @property {string} title
+ * @property {string} link Absolute URL (also used as the `<guid>`).
+ * @property {string} pubDate RFC-822 date, or "" to omit.
+ * @property {string} description
+ */
+/**
+ * Build `rss.xml` (RSS 2.0) for the dated posts. The caller selects, sorts
+ * (date desc), and caps the items; this builder just renders. Channel `<title>`
+ * / `<description>` come from the home frontmatter; `<link>` is the site origin
+ * and the `<atom:link rel="self">` points at the feed itself (RSS best practice).
+ * @param {{ title: string, description: string, siteUrl: string, feedUrl: string }} channel
+ * @param {RssItem[]} items
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildRss(channel: {
+    title: string;
+    description: string;
+    siteUrl: string;
+    feedUrl: string;
+}, items: RssItem[]): string;
+/**
+ * Build `robots.txt`. Always allows everything (hidden/draft routes are never
+ * built, so there's nothing to `Disallow`). The `Sitemap:` line is included
+ * ONLY when `siteUrl` is set — a sitemap URL is only meaningful with an origin.
+ * @param {string} [siteUrl] Absolute origin, or "" / undefined to omit the line.
+ * @returns {string} The robots.txt body (trailing newline).
+ */
+export function buildRobots(siteUrl?: string): string;
+/** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
+export const RSS_ITEM_LIMIT: 20;
+export type Route = import("./router.js").Route;
+/**
+ * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
+ * ready for a sitemap `<lastmod>`.
+ */
+export type DatedRoute = {
+    /**
+     * Absolute URL (`site_url` + route path).
+     */
+    loc: string;
+    /**
+     * ISO date (`yyyy-mm-dd`).
+     */
+    lastmod: string;
+};
+/**
+ * An RSS item — a dated post in feed order.
+ */
+export type RssItem = {
+    title: string;
+    /**
+     * Absolute URL (also used as the `<guid>`).
+     */
+    link: string;
+    /**
+     * RFC-822 date, or "" to omit.
+     */
+    pubDate: string;
+    description: string;
+};

package/types/src/headers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The full security-header set for one response, including the CSP variant.
+ * @param {boolean} reactive Whether the route ships the reactive runtime.
+ * @returns {Record<string, string>}
+ */
+export function securityHeaders(reactive: boolean): Record<string, string>;
+/**
+ * The exact body of the inline `<script type="speculationrules">` block that
+ * `compilePage` emits for `transitions: true` pages. Kept in sync with
+ * `src/compiler/page.js` by a drift-guard test that hashes the block out of a
+ * real build — if the emitted rules change, that test fails before the CSP
+ * silently starts blocking prerender.
+ * @type {string}
+ */
+export const SPECULATION_RULES_JSON: string;
+/**
+ * CSP hash source for the speculationrules block — computed from the constant
+ * above at module load, never hand-maintained.
+ * @type {string}
+ */
+export const SPECULATION_RULES_HASH: string;
+/**
+ * CSP for reactive pages. Since 2.1 the runtime WALKS a compile-time-validated
+ * expression AST instead of building a `new Function`, so reactive pages no longer
+ * need `'unsafe-eval'` — this policy is byte-identical to the static one. The only
+ * script source is same-origin `/__wd/runtime.js` (plus the hashed speculationrules
+ * block); no `'unsafe-inline'`, no `'unsafe-eval'`.
+ * @type {string}
+ */
+export const REACTIVE_CSP: string;
+/**
+ * CSP for static pages (zero framework JS). Identical to the reactive policy now
+ * that neither variant evals — kept as a distinct export so the per-route emit and
+ * the `securityHeaders()` callers stay explicit about intent. Inline `<style>`
+ * (view transitions) keeps `'unsafe-inline'` on style-src only.
+ * @type {string}
+ */
+export const STATIC_CSP: string;
+/**
+ * Baseline security headers applied to every HTML response, independent of the
+ * CSP. CSP is added per-route (static vs reactive) by the helpers below.
+ * @type {Record<string, string>}
+ */
+export const BASE_SECURITY_HEADERS: Record<string, string>;

package/types/src/highlight.d.ts

@@ -0,0 +1,24 @@
+/**
+ * markdown-it `highlight` callback. Returns highlight.js's escaped token HTML for
+ * a known language (wrapped so the `hljs` marker is always present), or `""` to
+ * defer to markdown-it's own escaping for an unknown/absent language — the
+ * graceful-degradation path that renders a plain `<code>` with no highlighting.
+ *
+ * markdown-it does NOT escape a non-empty return value (it is trusted HTML), so
+ * we must return already-escaped content — `hljs.highlight` escapes its output.
+ * @param {string} code The fenced block's raw source.
+ * @param {string} lang The info string (language) after the opening fence, if any.
+ * @returns {string} Highlighted, escaped HTML, or `""` to defer to markdown-it.
+ */
+export function highlightCode(code: string, lang: string): string;
+/**
+ * Detect whether a rendered HTML fragment contains a highlighted code block, so
+ * the page-level `assets.hasCode` flag (and thus the highlight stylesheet) is set
+ * only when highlighting actually happened. Matches the `hljs` marker stamped by
+ * {@link highlightCode}; a page with only plain/unknown-language code never trips it.
+ * @param {string} html Rendered body HTML.
+ * @returns {boolean}
+ */
+export function htmlHasHighlight(html: string): boolean;
+export const HLJS_MARKER: "hljs";
+export const HIGHLIGHT_CSS: "/* Darkmown syntax highlighting \u2014 highlight.js classes mapped to $code-* skin\n   tokens. Dark mode is automatic: the tokens swap under tokens dark / :theme,\n   so this stylesheet ships zero JavaScript. */\n.hljs {\n  color: var(--code-fg, #e9efe7);\n  background: var(--code-bg, #1b2420);\n}\n.hljs-comment,\n.hljs-quote {\n  color: var(--code-comment, #7d8a82);\n  font-style: italic;\n}\n.hljs-keyword,\n.hljs-selector-tag,\n.hljs-literal,\n.hljs-section,\n.hljs-doctag,\n.hljs-name {\n  color: var(--code-keyword, #d39bda);\n}\n.hljs-string,\n.hljs-regexp,\n.hljs-meta .hljs-string,\n.hljs-attr,\n.hljs-selector-attr,\n.hljs-selector-pseudo,\n.hljs-addition {\n  color: var(--code-string, #8fd28a);\n}\n.hljs-title,\n.hljs-title.function_,\n.hljs-built_in,\n.hljs-class .hljs-title,\n.hljs-selector-class,\n.hljs-selector-id {\n  color: var(--code-function, #82c0e9);\n}\n.hljs-number,\n.hljs-symbol,\n.hljs-bullet,\n.hljs-link,\n.hljs-meta {\n  color: var(--code-number, #e3a76f);\n}\n.hljs-variable,\n.hljs-template-variable,\n.hljs-type,\n.hljs-attribute,\n.hljs-params,\n.hljs-tag,\n.hljs-deletion,\n.hljs-punctuation,\n.hljs-operator {\n  color: var(--code-punctuation, #b9c4be);\n}\n.hljs-emphasis {\n  font-style: italic;\n}\n.hljs-strong {\n  font-weight: 600;\n}\n";

package/types/src/router.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import("./compiler.js").Meta} Meta
+ */
+/**
+ * A discovered page route: the source file, its public route path, and its
+ * parsed frontmatter. `meta` is read ONCE here — the single source of truth for
+ * "is this a draft" and for the downstream sitemap/RSS feeds (which never see a
+ * draft, since drafts are filtered out below).
+ * @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/`).
+ * @property {Meta} meta Parsed frontmatter for the file.
+ */
+/**
+ * Walk `routesRoot` and collect page routes, sorted and de-duplicated.
+ *
+ * Drafts are filtered HERE, at the one route-discovery chokepoint, so every
+ * downstream consumer (the build, `routes.json`, the sitemap, the RSS feed)
+ * only ever sees the post-filter list — a `draft: true` page can never leak. By
+ * default drafts are excluded; pass `{ includeDrafts: true }` (`darkmown dev`
+ * and `darkmown build --drafts`) to keep them. This is distinct from, and
+ * orthogonal to, the permanent `.`/`-`/`_` filename hiding above: hidden names
+ * are private forever; `draft:` is a toggleable, publish-when-ready gate.
+ * @param {string} routesRoot Absolute path to `site/pages`.
+ * @param {{ includeDrafts?: boolean }} [options]
+ * @returns {Route[]}
+ */
+export function discoverRoutes(routesRoot: string, options?: {
+    includeDrafts?: boolean;
+}): Route[];
+/**
+ * Whether a page's frontmatter marks it a draft (`draft: true`). The scalar
+ * frontmatter parser yields a boolean `true` or the string `"true"`, so accept
+ * both; any other value (absent, `false`, `"false"`) is not a draft.
+ * @param {Meta} meta
+ * @returns {boolean}
+ */
+export function isDraft(meta: Meta): boolean;
+/**
+ * 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: string, file: string): string;
+/**
+ * Map a public route to the `index.html` output path under `distRoot`.
+ *
+ * Defense in depth: routes come from `routeFromFile` walking `site/pages`, so
+ * they can't normally carry traversal segments — but any future caller passing
+ * an unvetted route must not be able to write outside the build output. The
+ * resolved path is asserted to stay inside `distRoot`.
+ * @param {string} distRoot Absolute path to the build output directory.
+ * @param {string} route Public route path.
+ * @returns {string}
+ */
+export function outputPathForRoute(distRoot: string, route: string): string;
+export type Meta = import("./compiler.js").Meta;
+/**
+ * A discovered page route: the source file, its public route path, and its
+ * parsed frontmatter. `meta` is read ONCE here — the single source of truth for
+ * "is this a draft" and for the downstream sitemap/RSS feeds (which never see a
+ * draft, since drafts are filtered out below).
+ */
+export type Route = {
+    /**
+     * Absolute path to the source `.md`/`.wd` file.
+     */
+    file: string;
+    /**
+     * Public route path (always trailing-slashed, e.g. `/about/`).
+     */
+    route: string;
+    /**
+     * Parsed frontmatter for the file.
+     */
+    meta: Meta;
+};

package/types/src/scaffold.d.ts

@@ -0,0 +1,20 @@
+/**
+ * List the available scaffold templates (directory names under `src/templates`).
+ * @returns {string[]}
+ */
+export function availableTemplates(): string[];
+/**
+ * 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.
+ * @param {{ template?: string }} [options] `template` defaults to `"starter"`.
+ * @returns {{ root: string, template: string }}
+ */
+export function initProject(root: string, options?: {
+    template?: string;
+}): {
+    root: string;
+    template: string;
+};

package/types/src/skin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Derive a short, deterministic scope id from a skin's PROJECT-RELATIVE PATH.
+ * Path-based (stable across content edits, unique per component file) and short
+ * enough to read in the emitted CSS (`wd-7c21`). The same path always yields the
+ * same id, so the CSS rewrite (builder) and the HTML stamp (page/include) agree
+ * without sharing state — they just hash the same relative path. The path is
+ * normalized to POSIX separators first so a build is identical on Windows.
+ * @param {string} relPath Skin path relative to the project root (cwd).
+ * @returns {string} The scope id, e.g. `wd-7c21`.
+ */
+export function scopeIdFor(relPath: string): string;
+/**
+ * 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.
+ *
+ * Scoping (opt-in): when `opts.scope` is set the skin is compiled in scoped
+ * mode — every selector RULE gets `[data-wd-scope="<id>"]` appended to the
+ * subject of each compound selector, so the stylesheet only ever matches inside
+ * the stamped subtree. Design tokens (`tokens` / `tokens dark` / `tokens [attr]`)
+ * stay GLOBAL on `:root` regardless, so `var(--x)` and dark mode keep working
+ * site-wide. A whole-selector `:global(.x)` escapes scoping. Page-level selectors
+ * (`page`/`*`/`html`/`body`/`::selection`) are a compile error in scoped mode.
+ * Without `opts.scope`, output is byte-identical to before this feature existed.
+ * @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.
+ * @returns {string}
+ */
+export function compileSkin(source: string, opts?: {
+    scope?: string;
+    subjects?: Set<string>;
+}): string;
+/**
+ * A nesting frame in the indentation stack.
+ */
+export type SkinFrame = {
+    indent: number;
+    selector: string | null;
+    media?: string | undefined;
+};

package/types/src/statics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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: string, url: string, res: http.ServerResponse): void;
+/**
+ * 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: string, url: string): string | null;
+/**
+ * Map a file path to a response content-type by extension, defaulting to
+ * `application/octet-stream` for unknown types.
+ * @param {string} file File path or name.
+ * @returns {string}
+ */
+export function contentType(file: string): string;
+import http from "node:http";

package/types/statics.d.ts

@@ -15,7 +15,8 @@ export function serve(distRoot: string, url: string, res: http.ServerResponse):
  */
 export function resolvePublicFile(distRoot: string, url: string): string | null;
 /**
- * Map a file path to a response content-type, defaulting to `text/html`.
+ * Map a file path to a response content-type by extension, defaulting to
+ * `application/octet-stream` for unknown types.
  * @param {string} file File path or name.
  * @returns {string}
  */