@zvndev/darkmown 2.6.1-next.12.ge562f5d → 2.7.0

package/types/compiler/interpolation.d.ts

@@ -59,6 +59,23 @@ export function resolveStateKey(name: string, ctx: Ctx): string | null;
  * @returns {string}
  */
 export function interpolateLeaf(value: unknown, expr: string, ctx: Ctx): string;
+/**
+ * Render the INITIAL value of a reactive binding (`data-wd-bind` /
+ * `data-wd-each`) as text.
+ *
+ * Identical to {@link interpolateLeaf} except for arrays: the runtime paints a
+ * bind by assigning to `textContent`, which coerces `["a", "b"]` with `String()`
+ * to `"a,b"`, and the loop row-template fill already agrees (it escapes through
+ * `String()` too). `interpolateLeaf`'s `", "` join is the STATIC contract — the
+ * documented `{ meta.tags }` behavior for a value nothing will ever repaint — so
+ * the two cannot share one rule. Painting the static form here made the first
+ * reactive render silently rewrite `"a, b"` to `"a,b"`.
+ * @param {unknown} value
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function interpolateBound(value: unknown, expr: string, ctx: Ctx): string;
 /**
  * JSON-encode a value for an inline `<script>`, escaping `<` to stay HTML-safe.
  * @param {unknown} value
@@ -96,6 +113,12 @@ export function stripQuotes(value?: string): string;
  * @returns {string}
  */
 export function humanizeName(name: string): string;
+/**
+ * True for a value that must never be applied to a bound `href`/`src`.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function unsafeUrlValue(value: unknown): boolean;
 /**
  * Escape a value for safe inclusion in HTML text and attribute contexts.
  * @param {unknown} value

package/types/compiler/loops.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Serialize an already-validated expression fragment into the compact AST
+ * attribute payload the runtime reads, turning a residual parse failure into a
+ * CODED compile error with `file:line` instead of the AST layer's raw internal
+ * `Error`.
+ *
+ * `expr-ast.js` re-parses the compiler's own output, so a failure there is not
+ * an author mistake and it throws a plain `Error` by design. But the operand
+ * folds in `predicates.js` splice BUILD-TIME VALUES into that output, and a
+ * value the fold cannot render as a readable literal escapes as an uncoded
+ * `expr-ast: …` error with no file, no line, and no suggestion — the one gap in
+ * the "every author-facing error carries a code" invariant. This is the seam
+ * where that becomes an ordinary Darkmown compile error again.
+ *
+ * Lives here rather than beside its `structure.js` callers because the error-code
+ * registry pins each source file to a subsystem block (`compiler/loops.js` owns
+ * WD1xx), and this guard's reserved code is WD190.
+ * @param {string} code Validated JS fragment over `I()`/`S()`/`C()`/`A()`.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the directive that owns it.
+ * @param {string} what Directive label for the message, e.g. `":if"`.
+ * @returns {any[]} The parsed AST.
+ */
+export function astAt(code: string, ctx: Ctx, index: number, what: string): any[];
 /**
  * @param {string} line
  * @param {string[]} bodyLines
@@ -9,6 +33,26 @@
  * @returns {string}
  */
 export function handleLoop(line: string, bodyLines: string[], emptyLines: string[] | null, ctx: Ctx, index: number, emptyStart?: number): string;
+/**
+ * Splice two adjacent tables into one, in the two shapes a `.wd` body produces:
+ *
+ * 1. Two tables that carry the SAME markup before `<tbody>` — one compiled row
+ *    body per loop row. Their `<tbody>` contents concatenate. Requiring the
+ *    prefixes to match is what keeps a header that interpolates the row (a
+ *    genuinely different table per row) from losing every header but the first.
+ * 2. A HEADER-ONLY table (a `<thead>` and no `<tbody>`: what `| Name | N |` +
+ *    `|---|---|` in the prose above a loop compiles to) followed by a BODY-ONLY
+ *    table (a `<tbody>` and no `<thead>`: what a loop over bare `|…|` rows now
+ *    emits). The body moves inside the header's table.
+ *
+ * Exported because both seams matter: the loop's own row seam (case 1) and the
+ * body-level seam between flushed prose and a handler's output (case 2), which
+ * `compileBody` owns.
+ * @param {string} prev
+ * @param {string} next
+ * @returns {string | null} The spliced HTML, or null when they do not merge.
+ */
+export function spliceTables(prev: string, next: string): string | null;
 /**
  * @param {string} str
  * @param {number} start
@@ -25,12 +69,15 @@ export function matchElement(str: string, start: number, tag: string): number;
 export function loopKeyOf(item: unknown, counts: Map<string, number>): string;
 /**
  * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Compilation} Compilation
  * @typedef {import("./context.js").Predicate} Predicate
  * @typedef {import("./context.js").NumArg} NumArg
  * @typedef {import("./context.js").LoopOpts} LoopOpts
  */
 export const LOOP_EXAMPLE: "@loop /products.json into p where p.price < 50 sort by p.price asc";
+export function serializeExprAt(code: string, ctx: Ctx, index: number, what: string): string;
 export type Ctx = import("./context.js").Ctx;
+export type Compilation = import("./context.js").Compilation;
 export type Predicate = import("./context.js").Predicate;
 export type NumArg = import("./context.js").NumArg;
 export type LoopOpts = import("./context.js").LoopOpts;

package/types/compiler/markdown.d.ts

@@ -5,11 +5,15 @@
  */
 export function selectMd(meta?: Meta): MarkdownIt;
 /**
+ * Render one prose chunk.
  * @param {string} text
  * @param {Ctx} ctx
+ * @param {number} [index] 0-based line index the chunk starts at in the current
+ *   `compileBody` slice, so a warning about a binding inside it reports the true
+ *   `file:line`. Defaults to the top of the slice.
  * @returns {string}
  */
-export function renderProse(text: string, ctx: Ctx): string;
+export function renderProse(text: string, ctx: Ctx, index?: number): string;
 /**
  * The inline token an attr block attaches to: the immediately-preceding image
  * (self-closing) or the open token matching the immediately-preceding close
@@ -29,6 +33,64 @@ export function attrTarget(children: any[], i: number): any;
  * @returns {string}
  */
 export function slugify(text: string): string;
+export { unsafeUrlValue };
+export function encodeDest(value: unknown): string;
+/**
+ * A resolved `{ name.path }` binding.
+ */
+export type Binding = {
+    /**
+     * What the inline rule emits: a `data-wd-each` /
+     * `data-wd-bind` span for a reactive value, the escaped value for a static one.
+     */
+    html: string;
+    /**
+     * The PLAIN resolved text (unescaped, no markup) — a
+     * reactive value's initial paint. This is what a link destination, a raw-HTML
+     * attribute, and a heading slug need; `html` is unusable in all three.
+     */
+    text: string;
+    /**
+     * Where the value came from, and
+     * therefore what the non-inline positions may do with it: `static` is a
+     * build-time value and always safe to substitute; `state` is `:state`/`:store`
+     * and paints its seed then binds; `row` is a reactive `@loop` row, whose ONE
+     * template serves every row, so it paints nothing and binds per row.
+     */
+    kind: "static" | "state" | "row";
+    /**
+     * For `state`: the fully-qualified state key.
+     */
+    key?: string | undefined;
+    /**
+     * For `state`/`row`: the dotted sub-path under it ("" for the whole value).
+     */
+    path?: string | undefined;
+    /**
+     * For `row`: the per-row meta variable (`index`, `number`, …).
+     */
+    meta?: string | undefined;
+};
 export type Meta = import("./context.js").Meta;
 export type Ctx = import("./context.js").Ctx;
+/**
+ * One reactive binding found in a destination: the serialized template part the
+ * runtime evaluates, plus the build-time text to paint for it.
+ */
+export type PendingAttr = {
+    /**
+     *   `s` = state key + sub-path, `i` = loop-row sub-path, `m` = row meta variable.
+     */
+    part: ["s", string, string] | ["i", string] | ["m", string];
+    /**
+     * Build-time paint ("" for anything per-row).
+     */
+    text: string;
+    /**
+     * The author's own `{ … }` source, restored when the
+     * `](…)` turned out not to be a link after all.
+     */
+    raw: string;
+};
 import MarkdownIt from "markdown-it";
+import { unsafeUrlValue } from "./interpolation.js";

package/types/compiler/predicates.d.ts

@@ -8,12 +8,18 @@ export function compilePredicate(raw: string, itemName: string, ctx: Ctx): Predi
 /**
  * Evaluate a compiled predicate against a row at build time by walking its AST —
  * the same closed evaluator the runtime uses, so the fold matches. No eval.
+ *
+ * `what` names the CONSTRUCT the body came from. Three directives share this
+ * evaluator (`@loop … where`, `::: … .class when`, `:if`), and the warning used
+ * to say "@loop where predicate … treating the row as excluded" for all of
+ * them — pointing an author at a loop they never wrote when a `:if` folded.
  * @param {string} body
  * @param {unknown} item
  * @param {Ctx} ctx
+ * @param {string} [what] Directive label, e.g. `":if"`. Defaults to `@loop where`.
  * @returns {boolean}
  */
-export function evalPredicate(body: string, item: unknown, ctx: Ctx): boolean;
+export function evalPredicate(body: string, item: unknown, ctx: Ctx, what?: string): boolean;
 /**
  * Compile a `::: … .class when <predicate>`. Allows `:if`-style bare truthy
  * paths and `where`-style `left <op> right` conditions joined by `and`/`or`.

package/types/compiler/state.d.ts

@@ -31,8 +31,13 @@ export function handleStore(line: string, ctx: Ctx, index: number): string;
  */
 export function declareStore(name: string, value: unknown, ctx: Ctx): string;
 /**
- * Seed a `<name>_error` state key (null) if absent. Shared by :fetch and the
- * round-trip :form so error fallbacks have a key to bind.
+ * Seed the `<name>_error` / `<name>_error_body` pair (null) if absent. Shared by
+ * `:fetch` and the round-trip `:form` so error fallbacks have a key to bind.
+ *
+ * `_error` is what the server SAID — its JSON `error`/`message` field when the
+ * body has one, else `HTTP <status>`. `_error_body` is the whole parsed body,
+ * so a page can render field-level errors (`{ signup_error_body.fields.email }`)
+ * without a colocated script.
  * @param {string} key
  * @param {Ctx} ctx
  * @returns {void}
@@ -65,4 +70,5 @@ export const STATE_EXAMPLE: ":state count = 0";
 export const STORE_EXAMPLE: ":store cart = []";
 export const COMPUTED_EXAMPLE: ":computed total = items.length * 4";
 export const THEME_EXAMPLE: ":theme";
+export const URL_STATE_EXAMPLE: ":state q = \"\" from-url";
 export type Ctx = import("./context.js").Ctx;

package/types/compiler/structure.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Peel the leading run of whitelisted accessibility attributes off `rest`.
+ *
+ * Stops at the first token that does not open like an attribute (a `.class`, a
+ * `#id`, a `->`, or the end of the line) and hands that remainder back. A token
+ * that DOES open like an attribute but is misspelt, unquoted, or outside the
+ * whitelist is a compile error — never silently skipped.
+ * @param {string} rest Everything from the cursor to the end of the line.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @param {string} what Directive label for the message, e.g. `:button`.
+ * @returns {{ attrs: [string, string][], rest: string }}
+ */
+export function takeA11yAttrs(rest: string, ctx: Ctx, index: number, what: string): {
+    attrs: [string, string][];
+    rest: string;
+};
+/**
+ * Serialize validated attribute pairs into an HTML attribute string. The NAME
+ * came through {@link A11Y_ATTR_NAME} so it is inert; the VALUE is author text
+ * and is escaped.
+ * @param {[string, string][]} attrs
+ * @returns {string}
+ */
+export function a11yAttrHtml(attrs: [string, string][]): string;
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -40,7 +65,10 @@ export function handleCarousel(line: string, bodyLines: string[], ctx: Ctx, inde
  */
 export function handleIf(line: string, truthyLines: string[], falsyLines: string[], ctx: Ctx, index: number, falsyStart?: number): string;
 /**
- * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
+ * Render the documentation-demo directive `:try` (the "Try it" card the homepage
+ * uses). `:note` and `:sprint` lived here too and were deleted: nothing in the
+ * site, the docs, or the public directive set used them, and a directive the
+ * catalog does not list is a trap for an AI author that discovers it in source.
  * @param {string} line
  * @param {Ctx} ctx
  * @returns {string}
@@ -51,6 +79,9 @@ export function renderDemoDirective(line: string, ctx: Ctx): string;
  */
 export const INCLUDE_EXAMPLE: "@include /header.wd";
 export const CONTAINER_EXAMPLE: "::: card .featured";
+export const CONTAINER_A11Y_EXAMPLE: "::: card .note role=\"region\" aria-label=\"Notes\"";
 export const IF_EXAMPLE: ":if count > 0";
 export const CAROUSEL_EXAMPLE: ":carousel autoplay=3000";
+/** The corrective `Use:` tail every attribute error carries. */
+export const A11Y_ATTR_USE: "role=\"\u2026\", aria-\u2026=\"\u2026\", or title=\"\u2026\" (quoted static text)";
 export type Ctx = import("./context.js").Ctx;

package/types/feeds.d.ts

@@ -75,16 +75,58 @@ export function firstParagraph(body: string): string;
  * @returns {string}
  */
 export function rssDescription(meta: import("./compiler.js").Meta, file: string, body: string): string;
+/**
+ * Validate a frontmatter `date:` into a sitemap `<lastmod>` value, or "" when it
+ * is not one.
+ *
+ * This is the only feed value that used to be neither validated nor escaped, and
+ * both halves mattered: `date: 2026<bad&"q"` made the whole document
+ * unparseable, so NOTHING got indexed, and the far likelier `date: Jan 5, 2026`
+ * was silently truncated to `Jan 5, 202` by a blind 10-character slice. Returning
+ * "" (rather than guessing) lets the caller omit the element and say so — a
+ * sitemap entry with no `<lastmod>` is valid; one with a bogus date is not.
+ * @param {string} raw Trimmed frontmatter `date:` value.
+ * @returns {string} `yyyy-mm-dd`, or "" when `raw` is not a real calendar date.
+ */
+export function sitemapDate(raw: 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
+ * `site_url` + path and `<lastmod>` from the supplied date. An empty `lastmod`
+ * omits the element rather than emitting a blank one. 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;
+/**
+ * Build a `<sitemapindex>` — the document that points at the numbered sitemap
+ * shards. No `<lastmod>` per shard: it would have to be the max over the shard's
+ * entries, which is a number nobody consumes and one more thing to keep true.
+ * @param {string[]} locs Absolute URLs of the shard files, in order.
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildSitemapIndex(locs: string[]): string;
+/**
+ * Plan the sitemap file(s) a set of entries needs.
+ *
+ * At or under {@link SITEMAP_URL_LIMIT} that is one `sitemap.xml`, byte-identical
+ * to what every site got before. Over it, the entries shard into
+ * `sitemap-1.xml`, `sitemap-2.xml`, … and `sitemap.xml` becomes the
+ * `<sitemapindex>` pointing at them — so `robots.txt` keeps naming
+ * `/sitemap.xml` and every existing submission stays valid.
+ *
+ * Returned rather than written so the split is a pure function the tests can
+ * drive with 50,001 synthetic entries without building 50,001 pages.
+ * @param {DatedRoute[]} entries
+ * @param {string} siteUrl Absolute origin, for the index's shard URLs.
+ * @returns {{ file: string, xml: string }[]} Shards first, `sitemap.xml` last.
+ */
+export function sitemapDocuments(entries: DatedRoute[], siteUrl: string): {
+    file: string;
+    xml: string;
+}[];
 /**
  * An RSS item — a dated post in feed order.
  * @typedef {object} RssItem
@@ -131,6 +173,26 @@ export function buildRobots(siteUrl?: string, policy?: string): string;
  * @returns {string} One of {@link AI_CRAWLER_POLICIES}.
  */
 export function aiCrawlerPolicy(meta: import("./compiler.js").Meta, file?: string): string;
+/**
+ * Resolve the site's RSS item cap from the HOME page's `rss_limit:` frontmatter.
+ *
+ * Darkmown has no config file by design: site-wide settings live in the home
+ * page's frontmatter next to `site_url` / `ai_crawlers`, and this is one of them.
+ * Absent means {@link RSS_ITEM_LIMIT}. A value that is not a positive integer
+ * THROWS rather than silently falling back, for the same reason `ai_crawlers`
+ * does: `rss_limit: 0` and `rss_limit: all` are both attempts to state a policy,
+ * and quietly publishing 20 items instead is the wrong failure direction.
+ * @param {import("./compiler.js").Meta} meta Home page frontmatter.
+ * @param {string} [file] Home page source path, for the error message.
+ * @returns {number} A positive integer.
+ */
+export function rssItemLimit(meta: import("./compiler.js").Meta, file?: string): number;
+/**
+ * The sitemap protocol's hard cap: 50,000 `<url>` entries per sitemap file. Over
+ * it, Google rejects the document outright — so a large site must split into
+ * numbered sitemaps behind a `<sitemapindex>`.
+ */
+export const SITEMAP_URL_LIMIT: 50000;
 /**
  * The AI crawler and answer-engine robots.txt tokens Darkmown names explicitly.
  *
@@ -159,7 +221,11 @@ export const AI_CRAWLERS: {
 }[];
 /** The accepted `ai_crawlers:` frontmatter values. */
 export const AI_CRAWLER_POLICIES: string[];
-/** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
+/**
+ * The DEFAULT most-recent-first RSS post cap — a feed is a recent window, not an
+ * archive. Overridable per site with `rss_limit:` on the home page
+ * ({@link rssItemLimit}).
+ */
 export const RSS_ITEM_LIMIT: 20;
 export type Route = import("./router.js").Route;
 /**

package/types/statics.d.ts

@@ -6,6 +6,31 @@
  * @returns {void}
  */
 export function serve(distRoot: string, url: string, res: http.ServerResponse): void;
+/**
+ * Whether a resolved path is something we can actually stream back: a regular
+ * file. A DIRECTORY is the case that matters — `fs.existsSync` says yes to one,
+ * and handing it to a read stream is an `EISDIR` on an unhandled `error` event,
+ * which takes the whole server process down. Treating it as a miss answers 404
+ * instead. Anything unstattable (absent, or a parent the process cannot read)
+ * is a miss too.
+ * @param {string} file Absolute path inside the build output.
+ * @returns {boolean}
+ */
+export function isServableFile(file: string): boolean;
+/**
+ * Stream a built file to the response with an `error` handler attached.
+ *
+ * `fs.createReadStream(file).pipe(res)` has none, so ANY read failure — a file
+ * deleted by a rebuild between the stat and the open, a permission error, a
+ * path that turned out not to be a regular file — is an unhandled `error` event
+ * and an immediate process exit. Here it answers instead: a 500 when the
+ * response has not started, and a clean end when it has (the status is already
+ * on the wire by then, so the truncated body is all we can signal with).
+ * @param {string} file Absolute path to the file to stream.
+ * @param {http.ServerResponse} res Response to write to.
+ * @returns {void}
+ */
+export function pipeFile(file: 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.