vagejs 0.1.0 → 0.2.0

package/dist/content/images.js

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Reads pixel dimensions from an image file's header (PNG, JPEG, GIF, WebP, SVG),
+ * without decoding it or adding a dependency. Undefined when the format isn't recognized.
+ */
+export function imageSize(file) {
+    let buf;
+    try {
+        buf = fs.readFileSync(file);
+    }
+    catch {
+        return undefined;
+    }
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".svg")
+        return svgSize(buf.toString("utf8"));
+    // PNG: width and height in the IHDR chunk.
+    if (buf.length >= 24 && buf.readUInt32BE(0) === 0x89504e47)
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    // GIF: little-endian logical screen size.
+    if (buf.length >= 10 && buf.toString("latin1", 0, 3) === "GIF")
+        return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    // WebP: lossy (VP8), lossless (VP8L) or extended (VP8X).
+    if (buf.length >= 30 && buf.toString("latin1", 0, 4) === "RIFF" && buf.toString("latin1", 8, 12) === "WEBP") {
+        const chunk = buf.toString("latin1", 12, 16);
+        if (chunk === "VP8 ")
+            return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+        if (chunk === "VP8L") {
+            const b = buf.readUInt32LE(21);
+            return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+        }
+        if (chunk === "VP8X")
+            return { width: buf.readUIntLE(24, 3) + 1, height: buf.readUIntLE(27, 3) + 1 };
+    }
+    // JPEG: walk the segments to the first start-of-frame marker.
+    if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+        let i = 2;
+        while (i + 9 < buf.length) {
+            if (buf[i] !== 0xff)
+                return undefined;
+            const marker = buf[i + 1];
+            const length = buf.readUInt16BE(i + 2);
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+            }
+            i += 2 + length;
+        }
+    }
+    return undefined;
+}
+function svgSize(svg) {
+    const tag = /<svg\b[^>]*>/i.exec(svg)?.[0];
+    if (!tag)
+        return undefined;
+    const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']\\s*([\\d.]+)(px)?\\s*["']`, "i").exec(tag)?.[1];
+    const w = attr("width");
+    const h = attr("height");
+    if (w && h)
+        return { width: Math.round(Number(w)), height: Math.round(Number(h)) };
+    const box = /\sviewBox\s*=\s*["']\s*[\d.-]+[\s,]+[\d.-]+[\s,]+([\d.]+)[\s,]+([\d.]+)\s*["']/i.exec(tag);
+    return box ? { width: Math.round(Number(box[1])), height: Math.round(Number(box[2])) } : undefined;
+}
+/**
+ * Fills in what Markdown images can't say: width and height from the file in public/
+ * (prevents layout shift), decoding="async", and loading="lazy" unless it's the first
+ * image (often the main one, which shouldn't wait). Attributes already present are kept;
+ * remote images only get the loading hints. Works on DOM elements, never on HTML text,
+ * so it can't change how the sanitized markup parses.
+ */
+export function enhanceImage(img, publicDir, first) {
+    const src = img.getAttribute("src");
+    if (src && !img.hasAttribute("width") && !img.hasAttribute("height") && /^\/(?!\/)/.test(src)) {
+        const size = localImageSize(src, publicDir);
+        if (size) {
+            img.setAttribute("width", String(size.width));
+            img.setAttribute("height", String(size.height));
+        }
+    }
+    if (!img.hasAttribute("decoding"))
+        img.setAttribute("decoding", "async");
+    if (!first && !img.hasAttribute("loading"))
+        img.setAttribute("loading", "lazy");
+}
+/** Size of a site-path image inside public/; undefined for bad paths or anything outside public/. */
+function localImageSize(src, publicDir) {
+    let rel;
+    try {
+        rel = decodeURIComponent(src.split(/[?#]/)[0]);
+    }
+    catch {
+        return undefined; // e.g. "/100%.png": not a valid encoded path
+    }
+    const file = path.join(publicDir, rel);
+    return file.startsWith(publicDir + path.sep) ? imageSize(file) : undefined;
+}

package/dist/content/markdown.d.ts

@@ -24,3 +24,5 @@ export interface MarkdownPage {
     html: string;
 }
 export declare function parseMarkdown(source: string, file: string): MarkdownPage;
+/** Frontmatter and Markdown body, without rendering HTML (cheap enough to run on every page). */
+export declare function parseFrontmatter(source: string, file: string): Omit<MarkdownPage, "html">;

package/dist/content/markdown.js

@@ -32,6 +32,11 @@ export const frontmatterSchema = z.looseObject({
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 const marked = new Marked({ gfm: true });
 export function parseMarkdown(source, file) {
+    const { frontmatter, body } = parseFrontmatter(source, file);
+    return { frontmatter, body, html: marked.parse(body, { async: false }) };
+}
+/** Frontmatter and Markdown body, without rendering HTML (cheap enough to run on every page). */
+export function parseFrontmatter(source, file) {
     const match = FRONTMATTER_RE.exec(source);
     let data = {};
     if (match) {
@@ -47,5 +52,5 @@ export function parseMarkdown(source, file) {
         throw new VageError(`Invalid frontmatter:\n${z.prettifyError(result.error)}`, file);
     }
     const body = match ? source.slice(match[0].length) : source;
-    return { frontmatter: result.data, body, html: marked.parse(body, { async: false }) };
+    return { frontmatter: result.data, body };
 }

package/dist/content/sanitize.d.ts

@@ -2,6 +2,15 @@
  * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
  * contributors or (later) CMS sources, so scripts, event handlers, javascript:
  * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
- * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ * attributes (used by analytics events) are kept. style="" is removed unless
+ * `markdown.inlineStyles` is on. Loaded lazily: jsdom is heavy.
+ *
+ * With `publicDir`, images get their size and loading hints inside the sanitizer
+ * (a DOMPurify hook), so DOMPurify's serialization is the final output.
  */
-export declare function sanitizeHtml(html: string): Promise<string>;
+export declare function sanitizeHtml(html: string, options?: {
+    publicDir?: string;
+    inlineStyles?: boolean;
+}): Promise<string>;
+/** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
+export declare function enhanceTrustedHtml(html: string, publicDir: string): Promise<string>;

package/dist/content/sanitize.js

@@ -1,17 +1,57 @@
+import { enhanceImage } from "./images.js";
 let purifier;
+let jsdom;
+async function load() {
+    if (!purifier) {
+        const [mod, { default: createDOMPurify }] = await Promise.all([import("jsdom"), import("dompurify")]);
+        jsdom = mod;
+        purifier = createDOMPurify(new mod.JSDOM("").window);
+    }
+    return { purifier, jsdom: jsdom };
+}
 /**
  * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
  * contributors or (later) CMS sources, so scripts, event handlers, javascript:
  * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
- * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ * attributes (used by analytics events) are kept. style="" is removed unless
+ * `markdown.inlineStyles` is on. Loaded lazily: jsdom is heavy.
+ *
+ * With `publicDir`, images get their size and loading hints inside the sanitizer
+ * (a DOMPurify hook), so DOMPurify's serialization is the final output.
  */
-export async function sanitizeHtml(html) {
-    if (!purifier) {
-        const [{ JSDOM }, { default: createDOMPurify }] = await Promise.all([import("jsdom"), import("dompurify")]);
-        purifier = createDOMPurify(new JSDOM("").window);
+export async function sanitizeHtml(html, options = {}) {
+    const { purifier } = await load();
+    let first = true;
+    const publicDir = options.publicDir;
+    const hook = (node) => {
+        if (publicDir && node.nodeName === "IMG") {
+            enhanceImage(node, publicDir, first);
+            first = false;
+        }
+    };
+    if (publicDir) {
+        purifier.addHook("afterSanitizeAttributes", hook);
     }
-    return purifier.sanitize(html, {
-        FORBID_TAGS: ["style", "form", "input", "button", "textarea", "select", "option", "base", "link", "meta", "object", "embed"],
-        ALLOW_DATA_ATTR: true,
-    });
+    try {
+        return purifier.sanitize(html, {
+            // font/marquee/center: legacy ways to hide or disguise text (white-on-white, 1px scrollers).
+            FORBID_TAGS: ["style", "form", "input", "button", "textarea", "select", "option", "base", "link", "meta", "object", "embed", "font", "marquee", "center"],
+            ALLOW_DATA_ATTR: true,
+            // Inline styles are the usual way to hide injected links (display:none, off-screen); layouts style pages.
+            // xlink:href: SVG links, which would slip past link checks.
+            FORBID_ATTR: options.inlineStyles ? ["xlink:href"] : ["style", "xlink:href"],
+        });
+    }
+    finally {
+        if (publicDir)
+            purifier.removeHook("afterSanitizeAttributes", hook);
+    }
+}
+/** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
+export async function enhanceTrustedHtml(html, publicDir) {
+    const { jsdom } = await load();
+    const template = new jsdom.JSDOM("").window.document.createElement("template");
+    template.innerHTML = html;
+    template.content.querySelectorAll("img").forEach((img, i) => enhanceImage(img, publicDir, i === 0));
+    return template.innerHTML;
 }

package/dist/core/clone.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copies plain data (objects and arrays) and keeps everything else as-is (URL, Date,
+ * class instances from Zod transforms), so values can be shared or frozen safely
+ * without breaking what layouts put in their schemas.
+ */
+export declare function clonePlain<T>(value: T): T;

package/dist/core/clone.js

@@ -0,0 +1,16 @@
+/**
+ * Copies plain data (objects and arrays) and keeps everything else as-is (URL, Date,
+ * class instances from Zod transforms), so values can be shared or frozen safely
+ * without breaking what layouts put in their schemas.
+ */
+export function clonePlain(value) {
+    if (Array.isArray(value))
+        return value.map(clonePlain);
+    if (value && typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clonePlain(v)]));
+    }
+    return value;
+}

package/dist/core/config.d.ts

@@ -10,6 +10,7 @@ export declare const configSchema: z.ZodObject<{
             allow: "allow";
             sanitize: "sanitize";
         }>>;
+        inlineStyles: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     seo: z.ZodDefault<z.ZodObject<{
         robots: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
@@ -95,9 +96,11 @@ export declare const configSchema: z.ZodObject<{
     deploy: z.ZodDefault<z.ZodObject<{
         target: z.ZodDefault<z.ZodEnum<{
             "cloudflare-pages": "cloudflare-pages";
+            "cloudflare-workers": "cloudflare-workers";
             "github-pages": "github-pages";
         }>>;
         cloudflareProject: z.ZodOptional<z.ZodString>;
+        cloudflareWorker: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     security: z.ZodDefault<z.ZodObject<{
         headers: z.ZodDefault<z.ZodBoolean>;
@@ -115,6 +118,12 @@ export declare const configSchema: z.ZodObject<{
             "script-src": "script-src";
             "style-src": "style-src";
         }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+        outboundLinks: z.ZodDefault<z.ZodEnum<{
+            lock: "lock";
+            off: "off";
+            require: "require";
+        }>>;
+        spamPatterns: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     guidelines: z.ZodDefault<z.ZodObject<{
         rulePack: z.ZodOptional<z.ZodString>;

package/dist/core/config.js

@@ -177,19 +177,31 @@ export const configSchema = z.strictObject({
             .enum(["sanitize", "allow"])
             .default("sanitize")
             .describe('"sanitize" removes scripts, event handlers, javascript: URLs, iframes and forms from page content. "allow" trusts all content authors.'),
+        inlineStyles: z
+            .boolean()
+            .default(false)
+            .describe('Keep style="..." attributes in page content (sanitize mode). Off by default: inline styles are the usual way to hide spam links. Put styling in layouts.'),
     })
-        .default({ html: "sanitize" }),
+        .default({ html: "sanitize", inlineStyles: false }),
     seo: seoSchema.default(() => seoSchema.parse({})),
     performance: performanceSchema.default(() => performanceSchema.parse({})),
     deploy: z
         .strictObject({
-        target: z.enum(["github-pages", "cloudflare-pages"]).default("github-pages").describe("Host used by `vage deploy`."),
+        target: z
+            .enum(["github-pages", "cloudflare-pages", "cloudflare-workers"])
+            .default("github-pages")
+            .describe("Host used by `vage deploy`. Cloudflare now creates new sites as Workers: prefer cloudflare-workers there."),
         cloudflareProject: z.string().regex(/^[a-z0-9][a-z0-9-]{0,57}$/).optional().describe("Cloudflare Pages project name."),
+        cloudflareWorker: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
+            .optional()
+            .describe("Cloudflare Worker name (cloudflare-workers target, when the project has no wrangler config). Defaults to cloudflareProject."),
     })
         .default({ target: "github-pages" }),
     security: z
         .strictObject({
-        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare Pages target)."),
+        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare targets)."),
         csp: z
             .enum(["enforce", "report-only", "off"])
             .default("enforce")
@@ -198,8 +210,13 @@ export const configSchema = z.strictObject({
             .partialRecord(z.enum(["script-src", "style-src", "img-src", "font-src", "connect-src", "frame-src", "media-src"]), z.array(z.string().regex(/^('[a-z0-9-]+'|https?:\/\/[^\s;,']+|[a-z]+:)$/, "must be a source like https://cdn.example.com or 'self'")))
             .default({})
             .describe("Extra sources per directive, e.g. { \"connect-src\": [\"https://api.example.com\"] }."),
+        outboundLinks: z
+            .enum(["require", "lock", "off"])
+            .default("lock")
+            .describe('"lock": when links.lock.json exists, every external domain the site links to must be listed there (approve with `vage links approve`); new domains fail `vage check`. Catches injected spam links. "require": the same, and a missing links.lock.json is an error, so deleting it can\'t switch the guard off. "off": no guard.'),
+        spamPatterns: z.boolean().default(true).describe("Warn in `vage check` about common spam words (casino, pills, payday loans...) in page text and links."),
     })
-        .default({ headers: true, csp: "enforce", cspSources: {} }),
+        .default({ headers: true, csp: "enforce", cspSources: {}, outboundLinks: "lock", spamPatterns: true }),
     guidelines: z
         .strictObject({
         rulePack: z

package/dist/core/errors.d.ts

@@ -1,5 +1,7 @@
 /** An expected, user-facing error. The CLI prints its message without a stack trace. */
 export declare class VageError extends Error {
     readonly file?: string | undefined;
+    /** The message without the "at <file>" suffix. */
+    readonly detail: string;
     constructor(message: string, file?: string | undefined);
 }

package/dist/core/errors.js

@@ -1,9 +1,12 @@
 /** An expected, user-facing error. The CLI prints its message without a stack trace. */
 export class VageError extends Error {
     file;
+    /** The message without the "at <file>" suffix. */
+    detail;
     constructor(message, file) {
         super(file ? `${message}\n  at ${file}` : message);
         this.file = file;
+        this.detail = message;
         this.name = "VageError";
     }
 }

package/dist/core/html.d.ts

@@ -1,2 +1,24 @@
 /** Escapes text for safe use in HTML content and attribute values. */
 export declare function escapeHtml(value: unknown): string;
+declare const SAFE: unique symbol;
+/** HTML that `html` inserts as-is. Create it with `html` or `raw()`; `String(x)` gives the markup. */
+export interface SafeHtml {
+    readonly [SAFE]: true;
+    readonly value: string;
+    toString(): string;
+}
+export declare const isSafeHtml: (v: unknown) => v is SafeHtml;
+/**
+ * Marks trusted markup so `html` won't escape it, such as `props.content` (already
+ * sanitized) or a JSON-LD script from `jsonLdScript()`. Never pass user or frontmatter text.
+ */
+export declare function raw(markup: string): SafeHtml;
+/**
+ * Template tag for layouts: every `${value}` is escaped unless it is `html` itself or `raw()`.
+ * Arrays are joined, and null, undefined and false render nothing, so lists and conditions read naturally:
+ *
+ *   html`<ul>${posts.map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>`
+ *   html`<main>${raw(content)}</main>`
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): SafeHtml;
+export {};

package/dist/core/html.js

@@ -9,3 +9,34 @@ const ESCAPES = {
 export function escapeHtml(value) {
     return String(value ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]);
 }
+const SAFE = Symbol.for("vagejs.safeHtml");
+const safe = (value) => ({ [SAFE]: true, value, toString: () => value });
+export const isSafeHtml = (v) => typeof v === "object" && v !== null && SAFE in v;
+/**
+ * Marks trusted markup so `html` won't escape it, such as `props.content` (already
+ * sanitized) or a JSON-LD script from `jsonLdScript()`. Never pass user or frontmatter text.
+ */
+export function raw(markup) {
+    return safe(String(markup));
+}
+function interpolate(v) {
+    if (isSafeHtml(v))
+        return v.value;
+    if (Array.isArray(v))
+        return v.map(interpolate).join("");
+    if (v === null || v === undefined || v === false)
+        return "";
+    return escapeHtml(v);
+}
+/**
+ * Template tag for layouts: every `${value}` is escaped unless it is `html` itself or `raw()`.
+ * Arrays are joined, and null, undefined and false render nothing, so lists and conditions read naturally:
+ *
+ *   html`<ul>${posts.map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>`
+ *   html`<main>${raw(content)}</main>`
+ */
+export function html(strings, ...values) {
+    let out = strings[0];
+    values.forEach((v, i) => (out += interpolate(v) + strings[i + 1]));
+    return safe(out);
+}

package/dist/core/pages.d.ts

@@ -0,0 +1,40 @@
+import { type Frontmatter } from "../content/markdown.js";
+import type { ModuleLoader, SiteConfig } from "./config.js";
+/** One published page, as layouts see it in `props.pages`. */
+export interface PageSummary {
+    /** URL path with a trailing slash, e.g. "/blog/first-post/". */
+    route: string;
+    /** Absolute canonical URL, when `site` is set and the page is indexable. */
+    url?: string;
+    title: string;
+    description?: string;
+    /** Source path relative to the project root, e.g. "src/pages/blog/first-post.md". */
+    source: string;
+    frontmatter: Frontmatter;
+}
+/**
+ * Every published page (drafts and 404.md excluded), sorted by route. Reads frontmatter
+ * and applies each page's layout schema, so list entries get the same defaults as the
+ * page itself. The result is frozen: layouts share it, so none may change it.
+ * `skipInvalid` (dev server, `vage check`) leaves out pages whose frontmatter is invalid;
+ * they report their own error instead of breaking every page that lists others.
+ */
+export declare function collectPages(root: string, site: SiteConfig, load: ModuleLoader, options?: {
+    skipInvalid?: boolean;
+}): Promise<readonly PageSummary[]>;
+export interface CollectionOptions {
+    /** Only pages below this route, e.g. "/blog/". The section's own index page is left out unless `includeIndex`. */
+    under?: string;
+    includeIndex?: boolean;
+    /**
+     * "date": newest `datePublished` first (undated pages last, then by title).
+     * "title": A to Z. "route" (default): by URL. Or a compare function.
+     */
+    sort?: "date" | "title" | "route" | ((a: PageSummary, b: PageSummary) => number);
+    limit?: number;
+}
+/**
+ * Picks and orders pages for lists such as a blog index, a sidebar or "latest posts":
+ *   collection(pages, { under: "/blog/", sort: "date", limit: 5 })
+ */
+export declare function collection(pages: readonly PageSummary[], options?: CollectionOptions): PageSummary[];

package/dist/core/pages.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../content/markdown.js";
+import { pageMeta } from "../seo/head.js";
+import { clonePlain } from "./clone.js";
+import { applyLayoutFields } from "./render.js";
+import { VageError } from "./errors.js";
+import { discoverRoutes } from "./routes.js";
+/**
+ * Every published page (drafts and 404.md excluded), sorted by route. Reads frontmatter
+ * and applies each page's layout schema, so list entries get the same defaults as the
+ * page itself. The result is frozen: layouts share it, so none may change it.
+ * `skipInvalid` (dev server, `vage check`) leaves out pages whose frontmatter is invalid;
+ * they report their own error instead of breaking every page that lists others.
+ */
+export async function collectPages(root, site, load, options = {}) {
+    const pagesDir = path.join(root, "src", "pages");
+    const out = [];
+    for (const entry of discoverRoutes(pagesDir)) {
+        let frontmatter;
+        try {
+            ({ frontmatter } = parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file));
+            if (frontmatter.draft)
+                continue;
+            await applyLayoutFields(root, frontmatter, load, entry.file);
+        }
+        catch (err) {
+            // Any failure (bad frontmatter, a layout that throws or doesn't compile) is that page's own error.
+            if (options.skipInvalid)
+                continue;
+            throw err;
+        }
+        out.push({
+            route: entry.route,
+            url: pageMeta(site, entry.route, frontmatter).canonical,
+            title: frontmatter.title,
+            description: frontmatter.description,
+            source: path.relative(root, entry.file),
+            frontmatter,
+        });
+    }
+    // A frozen deep copy: shared by every layout, and never the objects a page renders with.
+    return deepFreeze(clonePlain(out));
+}
+/** Freezes plain data only; URL/Date/class instances from schema transforms stay usable. */
+function deepFreeze(value) {
+    const plain = Array.isArray(value) || (value && typeof value === "object" && [Object.prototype, null].includes(Object.getPrototypeOf(value)));
+    if (plain && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+const SORTS = ["date", "title", "route"];
+/**
+ * Picks and orders pages for lists such as a blog index, a sidebar or "latest posts":
+ *   collection(pages, { under: "/blog/", sort: "date", limit: 5 })
+ */
+export function collection(pages, options = {}) {
+    if (!Array.isArray(pages))
+        throw new VageError("collection(): pass the layout's `pages` as the first argument.");
+    const { under, includeIndex = false, sort = "route", limit } = options;
+    if (under !== undefined && !/^\/(?!\/)/.test(under)) {
+        throw new VageError(`collection(): "under" must be a site path starting with "/", like "/blog/" (got ${JSON.stringify(under)}).`);
+    }
+    if (typeof sort !== "function" && !SORTS.includes(sort)) {
+        throw new VageError(`collection(): "sort" must be "date", "title", "route" or a compare function (got ${JSON.stringify(sort)}).`);
+    }
+    if (typeof includeIndex !== "boolean")
+        throw new VageError(`collection(): "includeIndex" must be true or false (got ${JSON.stringify(includeIndex)}).`);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 0)) {
+        throw new VageError(`collection(): "limit" must be a whole number of 0 or more (got ${JSON.stringify(limit)}).`);
+    }
+    const prefix = under ? (under.endsWith("/") ? under : `${under}/`) : undefined;
+    const picked = pages.filter((p) => !prefix || (p.route.startsWith(prefix) && (includeIndex || p.route !== prefix)));
+    const byTitle = (a, b) => a.title.localeCompare(b.title);
+    const compare = typeof sort === "function"
+        ? sort
+        : sort === "title"
+            ? byTitle
+            : sort === "date"
+                ? (a, b) => {
+                    const da = a.frontmatter.datePublished ?? "";
+                    const db = b.frontmatter.datePublished ?? "";
+                    if (da !== db)
+                        return da && db ? db.localeCompare(da) : da ? -1 : 1;
+                    return byTitle(a, b);
+                }
+                : (a, b) => a.route.localeCompare(b.route);
+    const sorted = [...picked].sort(compare);
+    return limit === undefined ? sorted : sorted.slice(0, limit);
+}

package/dist/core/render.d.ts

@@ -1,6 +1,8 @@
 import { type Frontmatter } from "../content/markdown.js";
 import type { ModuleLoader, SiteConfig } from "./config.js";
+import { type SafeHtml } from "./html.js";
 import { type PageMeta } from "../seo/head.js";
+import type { PageSummary } from "./pages.js";
 export interface LayoutProps {
     /** Rendered page body HTML. Insert as-is; do not escape. */
     content: string;
@@ -13,8 +15,14 @@ export interface LayoutProps {
         frontmatter: Frontmatter;
     };
     site: SiteConfig;
+    /**
+     * Every published page (drafts excluded), sorted by route. Use `collection()` to
+     * pick a section and order it, e.g. a blog index or a sidebar.
+     */
+    pages: readonly PageSummary[];
 }
-export type Layout = (props: LayoutProps) => string | Promise<string>;
+/** Returns the page's HTML: a string, or `html\`...\`` (escapes values automatically). */
+export type Layout = (props: LayoutProps) => string | SafeHtml | Promise<string | SafeHtml>;
 export interface RenderedPage {
     html: string;
     frontmatter: Frontmatter;
@@ -32,6 +40,14 @@ export declare function renderPage(options: {
     notFound?: boolean;
     /** Add configured analytics tags. Off in the dev server so development traffic is never measured. */
     analytics?: boolean;
+    /** Published pages for `props.pages`. */
+    pages?: readonly PageSummary[];
 }): Promise<RenderedPage>;
+/**
+ * Loads the page's layout and, if it exports a `frontmatter` schema, validates the page
+ * against it and fills in defaults (mutating `frontmatter`). Used for rendering and for
+ * `props.pages`, so both see the same values. Returns the layout function.
+ */
+export declare function applyLayoutFields(root: string, frontmatter: Frontmatter, load: ModuleLoader, file: string): Promise<Layout>;
 /** Used when a project has no src/layouts/default.ts. */
 export declare const defaultLayout: Layout;