vagejs 0.3.4 → 0.4.0

package/README.md

@@ -13,13 +13,18 @@
 
 # vagejs
 
-An AI-native, static-first web framework. Write pages in Markdown, and vagejs builds a fast static site with SEO, `llms.txt`, accessibility and security handled for you. It's built so AI coding agents can use it without guessing. **Pre-release (0.x).**
+**A free static site generator built for AI coding assistants.** Your assistant (Claude Code, Cursor, Codex, Copilot) writes the pages; vagejs checks them before anything goes live. Write pages in Markdown and get a fast static site with SEO, `llms.txt`, accessibility and security handled for you. **Pre-release (0.x).**
+
+[Website](https://vagejs.com) · [Docs](https://vagejs.com/docs/) · [Use with AI assistants](https://vagejs.com/agents/) · [Changelog](https://vagejs.com/changelog/) · [Discussions](https://github.com/agevenkat/vagejs/discussions)
+
+<p align="center"><img src="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/demo.svg" alt="Terminal demo: create a vagejs site, install it, npm run check catches a broken link and names the file, the link is fixed, the check passes, and npm start runs the site." width="760"></p>
 
 - **Static by default**: plain HTML, no client JavaScript unless you add analytics.
 - **SEO built in**: `robots.txt`, `sitemap.xml`, `llms.txt`, canonical URLs, Open Graph and JSON-LD, generated from your pages.
 - **Checks before you ship**: `vage check` (links, SEO, structured data, accessibility) and `vage audit` (page-weight budgets, axe, optional Lighthouse and PageSpeed).
 - **Safe by default**: page content is sanitized; secrets, build output and force-pushes are refused; Cloudflare deploys get a computed Content-Security-Policy.
 - **Agent-friendly**: every site ships with `AGENTS.md`, and `vage info --json` describes every command and config option.
+- **Runs everywhere**: macOS, Windows and Linux, tested on every change. Deploys to GitHub Pages and Cloudflare Workers built in; any static host (Vercel, Netlify) works with `npm run build` and the `dist` folder.
 
 ## Quick start
 
@@ -68,7 +73,7 @@ Our plans start at …
 
 Save it as `src/pages/pricing.md` and it's served at `/pricing/`. `title` is required. `description`, `draft`, `noindex`, `canonical`, `image`, `type: article`, `author`, `datePublished` and `dateModified` are optional; see [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md).
 
-Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` and `height` from the file, so the page doesn't jump while loading. With `images: { optimize: true }` (and `npm install --save-dev sharp`), vagejs also makes resized WebP copies of images in page content and offers them with `srcset`.
+Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` and `height` from the file, so the page doesn't jump while loading. With `images: { optimize: true }` (and `npm install --save-dev sharp`), vagejs also makes resized WebP copies of images in page content and offers them with `srcset`. Add `avif: true` for AVIF copies too, offered first through `<picture>` (usually smaller; slower to make). `vage audit` counts the copy browsers download, not the original.
 
 ### Navigation, feeds and AI extras
 
@@ -173,6 +178,15 @@ npx vage info --json    # commands, options, config and frontmatter JSON Schemas
 npx vage check --json   # findings with file, rule and fix hints
 ```
 
+Or let the assistant call vagejs directly over MCP. `npx vage mcp` runs an MCP server with read-only tools (`vage_info`, `vage_check`, `vage_pages`, `vage_links`); it needs the optional SDK:
+
+```bash
+npm install --save-dev @modelcontextprotocol/sdk
+claude mcp add --transport stdio --scope project vagejs -- npx -p vagejs vage mcp   # Claude Code, in the project folder
+```
+
+Other assistants: `{ "mcpServers": { "vagejs": { "command": "npx", "args": ["-p", "vagejs", "vage", "mcp", "--root", "/absolute/path/to/the/site"] } } }`. `-p vagejs` makes npx run the vagejs installed in the project, and never a different package that happens to be called `vage`. Approving link domains and deploying stay CLI commands for the site owner.
+
 ## Command reference
 
 ```bash
@@ -197,7 +211,7 @@ vage info     [--json]                            # commands + config/frontmatte
 
 ## Planned, not implemented
 
-Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server, AVIF images.
+Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes.
 
 ## Security
 
@@ -225,6 +239,8 @@ Also protect the accounts around the site: two-factor authentication on GitHub,
 
 ## Contributing
 
+New contributors are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and the issues labeled [good first issue](https://github.com/agevenkat/vagejs/labels/good%20first%20issue). Questions and ideas go in [Discussions](https://github.com/agevenkat/vagejs/discussions).
+
 ```bash
 npm install
 npm run typecheck

package/dist/audit/budgets.js

@@ -64,11 +64,31 @@ export function measurePages(outDir, pages, site) {
         for (const l of doc.querySelectorAll('link[rel="preload"][as="font"]'))
             add(l.getAttribute("href"), "font", route);
         for (const img of doc.querySelectorAll("img"))
-            add(img.getAttribute("src"), "image", route);
+            add(downloadedImage(img), "image", route);
         weight.total = Object.values(weight.bytes).reduce((a, b) => a + b, 0);
         return weight;
     });
 }
+/**
+ * The file a browser actually downloads for an <img>: the first <source> of its
+ * <picture> (AVIF from images.avif), else its srcset (WebP), else src. With several
+ * widths, the largest counts: what a wide, high-density screen loads.
+ */
+function downloadedImage(img) {
+    const source = img.parentNode?.rawTagName?.toLowerCase() === "picture" ? img.parentNode.querySelector("source[srcset]") : null;
+    const srcset = source?.getAttribute("srcset") ?? img.getAttribute("srcset");
+    if (!srcset)
+        return img.getAttribute("src");
+    let best;
+    for (const entry of srcset.split(",")) {
+        const [url, descriptor = "1x"] = entry.trim().split(/\s+/);
+        // "960w" (width) or "2x" (density): either way, the biggest number is the biggest file.
+        const size = Number(/^([\d.]+)[wx]$/.exec(descriptor)?.[1] ?? 0);
+        if (url && (!best || size > best.size))
+            best = { url, size };
+    }
+    return best?.url ?? img.getAttribute("src");
+}
 const BUDGET_KEYS = [
     ["javascriptKb", "javascript"],
     ["cssKb", "css"],

package/dist/cli/index.js

@@ -142,6 +142,35 @@ cli
     if (opts.open && target)
         openBrowser(target);
 }));
+cli
+    .command("new <kind> <name>", 'Start a page (vage new page pricing) or a post (vage new post "Our first launch") as a draft with valid frontmatter')
+    .option("--root <dir>", "Project root", { default: "." })
+    .option("--title <text>", "Page title (pages; default from the path)")
+    .option("--description <text>", "One or two sentences for search results")
+    .option("--under <folder>", "Posts: section folder under src/pages (default: blog)")
+    .option("--date <YYYY-MM-DD>", "Posts: datePublished (default: today)")
+    .option("--author <name>", "Posts: author (only written when given)")
+    .option("--slug <name>", "Posts: file name, for titles without Latin letters or digits")
+    .option("--json", "Print machine-readable JSON")
+    .action((kind, name, opts) => run(opts, async () => {
+    if (kind !== "page" && kind !== "post")
+        throw new VageError(`Unknown kind "${kind}". Use vage new page <path> or vage new post "<title>".`);
+    const { createPage } = await import("./new.js");
+    // cac turns numeric values (--title 123) into numbers, so every option is read as text.
+    const text = (v) => (v === undefined ? undefined : String(v));
+    const created = createPage(opts.root, kind, String(name), { title: text(opts.title), description: text(opts.description), under: text(opts.under), date: text(opts.date), author: text(opts.author), slug: text(opts.slug) });
+    if (opts.json)
+        return print({ ok: true, ...created });
+    console.log(`Created ${created.file} (draft) for ${created.route}`);
+    console.log("Preview it with npm start (drafts show there); remove `draft: true` to publish it, then run npm run check.");
+}));
+cli
+    .command("mcp", "Run an MCP server over stdio so AI assistants can check this site (read-only tools; needs @modelcontextprotocol/sdk)")
+    .option("--root <dir>", "Project root", { default: "." })
+    .action((opts) => run({}, async () => {
+    const { startMcpServer } = await import("../mcp/server.js");
+    await startMcpServer(opts.root, { version, info: () => frameworkInfo(cli, version) });
+}));
 cli
     .command("info", "Describe commands, config and frontmatter (use --json for agents)")
     .option("--json", "Print machine-readable JSON")
@@ -197,6 +226,12 @@ cli
         throw new VageError(`Unknown --target "${target}". Use github-pages, cloudflare-workers or cloudflare-pages.`);
     const { publish } = await import("../deploy/publish.js");
     const pages = await import("../deploy/github-pages.js");
+    // Stop before pushing a site GitHub Pages would serve from a subfolder (its links would break).
+    const { gitRaw } = await import("../deploy/git.js");
+    const origin = opts.remote ?? (await gitRaw(path.resolve(opts.root), ["remote", "get-url", "origin"]).catch(() => undefined))?.stdout?.trim();
+    const subfolder = pages.pagesSubfolderProblem(config.site, origin);
+    if (subfolder)
+        throw new VageError(subfolder);
     const result = await publish(opts.root, {
         ...opts,
         extraFiles: (branch) => ({ [pages.PAGES_WORKFLOW]: pages.pagesWorkflow(branch) }),

package/dist/cli/info.js

@@ -63,7 +63,7 @@ export function frameworkInfo(cli, version) {
             feeds: 'seo.feeds: [{ under: "/blog/" }] writes /blog/feed.xml (RSS 2.0) and links it from that section\'s pages',
             markdownCopies: "seo.markdownCopies: true publishes /<path>.md copies of listed pages, made from each page's <main> and linked with rel=alternate type=text/markdown; layouts mark repeated extras (share links, calls to action) with data-vage-copy=\"skip\". On Cloudflare, _headers gives each copy a canonical Link header to its page",
             lastmod: 'seo.lastmod: "git" takes sitemap <lastmod> from each page\'s last commit (dateModified wins; skipped in shallow clones)',
-            images: 'images: { optimize: true } (needs the sharp package) makes resized WebP copies of content images in /_vage/img/ and adds srcset/sizes',
+            images: 'images: { optimize: true } (needs the sharp package) makes resized WebP copies of content images in /_vage/img/ and adds srcset/sizes; images: { avif: true } also makes AVIF copies, offered first through <picture>',
             navigation: "frontmatter order and navTitle; helpers tree(), breadcrumbs(), neighbors(); PageSummary.label",
         },
         checks: {
@@ -108,8 +108,6 @@ export function frameworkInfo(cli, version) {
             "Netlify and Vercel deploy adapters",
             "CMS / external content-source adapters",
             "hreflang / multi-language sites, base paths, sitemap indexes",
-            "MCP server",
-            "AVIF images and <picture> (images.optimize makes WebP copies offered with srcset)",
         ],
     };
 }

package/dist/cli/new.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `vage new page <path>` and `vage new post <title>`: start a page with valid frontmatter.
+ * New files are drafts (`draft: true`), so placeholder text can't be published by
+ * accident: the dev server shows them, `vage build` skips them until the line is removed.
+ * Without a description, a comment marks where one goes (search engines then get the
+ * site's description, or nothing): vagejs never writes placeholder text that could publish.
+ */
+export interface NewOptions {
+    title?: string;
+    description?: string;
+    /** Posts: the section folder under src/pages (default "blog"). */
+    under?: string;
+    /** Posts: YYYY-MM-DD (default: today, local time). */
+    date?: string;
+    /** Posts: only written when given; vagejs never invents an author. */
+    author?: string;
+    /** Posts: the file name, when the title has no Latin letters or digits to make one from. */
+    slug?: string;
+}
+export interface Created {
+    file: string;
+    route: string;
+    draft: true;
+}
+/** "Getting Started: Part 2!" -> "getting-started-part-2" */
+export declare function slugify(text: string): string;
+export declare function createPage(root: string, kind: "page" | "post", name: string, options?: NewOptions): Created;

package/dist/cli/new.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { VageError } from "../core/errors.js";
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
+/** "Getting Started: Part 2!" -> "getting-started-part-2" */
+export function slugify(text) {
+    return text
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80)
+        .replace(/-+$/, "");
+}
+const titleFromSlug = (slug) => {
+    const last = slug.split("/").at(-1);
+    return last === "index" ? "Overview" : last.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
+};
+const today = () => {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+};
+/** YAML double-quoted scalars are JSON strings, so any title is written safely. */
+const yaml = (value) => JSON.stringify(value);
+export function createPage(root, kind, name, options = {}) {
+    const pagesDir = path.join(path.resolve(root), "src", "pages");
+    if (!fs.existsSync(pagesDir))
+        throw new VageError(`No src/pages folder in ${path.resolve(root)}. Run this inside a vagejs project.`);
+    // One line each: a line break would end up in the heading and fail the frontmatter schema.
+    for (const [label, value] of [["title", kind === "post" ? name : options.title], ["description", options.description], ["author", options.author]]) {
+        if (value !== undefined && /[\u0000-\u001f\u007f]/.test(value))
+            throw new VageError(`The ${label} must be one line of text, without line breaks or tabs.`);
+    }
+    let slug;
+    let title;
+    if (kind === "page") {
+        slug = name.replace(/^\/+|\/+$/g, "").replace(/\.md$/, "");
+        if (!SLUG.test(slug))
+            throw new VageError(`"${name}" isn't a valid page path. Use lowercase letters, numbers and hyphens, with / between folders (e.g. pricing or docs/setup).`);
+        title = options.title?.trim() || titleFromSlug(slug);
+    }
+    else {
+        title = name.trim();
+        if (!title)
+            throw new VageError('Give the post a title, e.g. vage new post "Our first launch".');
+        const under = (options.under ?? "blog").replace(/^\/+|\/+$/g, "");
+        if (!SLUG.test(under))
+            throw new VageError(`"${options.under}" isn't a valid section folder. Use lowercase letters, numbers, hyphens and /.`);
+        const base = options.slug !== undefined ? options.slug : slugify(title);
+        if (!base)
+            throw new VageError(`Couldn't make a file name from "${name}". Add --slug <name> (lowercase letters, numbers and hyphens).`);
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(base))
+            throw new VageError(`"${base}" isn't a valid --slug. Use lowercase letters, numbers and hyphens.`);
+        slug = `${under}/${base}`;
+    }
+    if (options.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(options.date))
+        throw new VageError(`--date must be YYYY-MM-DD, not "${options.date}".`);
+    const route = slug === "index" ? "/" : `/${slug.replace(/(^|\/)index$/, "")}/`.replace(/\/+/g, "/");
+    const rel = path.join("src", "pages", `${slug}.md`);
+    const file = path.join(pagesDir, `${slug}.md`);
+    // A page at /x/ can come from x.md or x/index.md: refuse either, never overwrite.
+    const twin = slug.endsWith("/index") ? path.join(pagesDir, `${slug.slice(0, -"/index".length)}.md`) : path.join(pagesDir, slug, "index.md");
+    for (const existing of [file, twin]) {
+        if (fs.existsSync(existing))
+            throw new VageError(`${path.relative(path.resolve(root), existing)} already exists, so ${route} is taken. Pick another name, or edit that file.`);
+    }
+    const lines = ["---", `title: ${yaml(title)}`];
+    if (options.description?.trim())
+        lines.push(`description: ${yaml(options.description.trim())}`);
+    else
+        lines.push("# description: one or two sentences for search results (until then, the site's description is used)");
+    if (kind === "post") {
+        lines.push("type: article", `datePublished: ${options.date ?? today()}`);
+        if (options.author?.trim())
+            lines.push(`author: ${yaml(options.author.trim())}`);
+    }
+    lines.push("# Remove the next line when the page is ready to publish.", "draft: true", "---", "", `# ${title}`, "", "Write here.", "");
+    // Never write through a symlinked folder: it can point outside the project.
+    let existing = path.dirname(file);
+    while (!fs.existsSync(existing))
+        existing = path.dirname(existing);
+    const realPages = fs.realpathSync(pagesDir);
+    const realParent = fs.realpathSync(existing);
+    if (realParent !== realPages && !realParent.startsWith(realPages + path.sep))
+        throw new VageError(`${path.relative(path.resolve(root), existing)} leads outside src/pages (a symlink?). Create the page in a regular folder.`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(file, lines.join("\n"), { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            throw new VageError(`${rel} already exists, so ${route} is taken. Pick another name, or edit that file.`);
+        throw err;
+    }
+    return { file: rel, route, draft: true };
+}

package/dist/content/optimize.d.ts

@@ -1,6 +1,7 @@
 /**
  * Opt-in image pipeline (images.optimize): resized WebP copies of the images used in
- * page content, offered to browsers with srcset. Needs the `sharp` package in the
+ * page content, offered to browsers with srcset; with images.avif, AVIF copies too,
+ * offered first through <picture>. Needs the `sharp` package in the
  * project. Results are cached in node_modules/.cache/vagejs/img, keyed by the file's
  * content and the settings, so unchanged images are never processed twice.
  */
@@ -9,15 +10,18 @@ export interface ImageOptions {
     widths: number[];
     quality: number;
     sizes: string;
+    avif?: boolean;
 }
 export interface Variants {
-    /** "url 480w, url 960w" */
+    /** "url 480w, url 960w" (WebP) */
     srcset: string;
+    /** The same widths as AVIF, when images.avif is on. */
+    avifSrcset?: string;
     /** Published path (e.g. "_vage/img/photo-ab12cd34-480.webp") -> cached file on disk. */
     files: Map<string, string>;
 }
-/** Turns an image into WebP at a given width. Injected in tests; sharp otherwise. */
-export type Resize = (input: Buffer, width: number, quality: number) => Promise<Buffer>;
+/** Turns an image into WebP (or AVIF) at a given width. Injected in tests; sharp otherwise. */
+export type Resize = (input: Buffer, width: number, quality: number, format?: "webp" | "avif") => Promise<Buffer>;
 export declare const IMAGE_DIR = "_vage/img";
 export declare function cacheDir(root: string): string;
 /** Loads sharp from the project (not from vagejs), with a clear message if it's missing. */

package/dist/content/optimize.js

@@ -23,7 +23,11 @@ export async function sharpResize(root) {
     }
     const sharp = (await import(pathToFileURL(resolved).href)).default;
     // rotate() applies EXIF orientation first, so phone photos aren't served sideways.
-    return (input, width, quality) => sharp(input).rotate().resize({ width, withoutEnlargement: true }).webp({ quality }).toBuffer();
+    // AVIF uses sharp's own default quality: its scale differs from WebP's, so images.quality would overshoot.
+    return (input, width, quality, format = "webp") => {
+        const resized = sharp(input).rotate().resize({ width, withoutEnlargement: true });
+        return (format === "avif" ? resized.avif() : resized.webp({ quality })).toBuffer();
+    };
 }
 /**
  * WebP variants for one site-path image in public/. Undefined for remote images,
@@ -61,30 +65,39 @@ export async function imageVariants(src, root, options, resize) {
     const dir = cacheDir(root);
     fs.mkdirSync(dir, { recursive: true });
     const files = new Map();
-    const entries = [];
-    for (const w of widths) {
-        const name = `${base}-${hash}-${w}.webp`;
-        const cached = path.join(dir, name);
-        if (!fs.existsSync(cached)) {
-            const tmp = `${cached}.${process.pid}.tmp`;
-            let data;
-            try {
-                data = await resize(input, w, options.quality);
+    const srcsets = {};
+    // Real widths, read from the WebP files; AVIF copies are resized the same way (vagejs can't read AVIF sizes).
+    const realWidth = new Map();
+    for (const format of options.avif ? ["webp", "avif"] : ["webp"]) {
+        const entries = [];
+        for (const w of widths) {
+            const name = `${base}-${hash}-${w}.${format}`;
+            const cached = path.join(dir, name);
+            if (!fs.existsSync(cached)) {
+                const tmp = `${cached}.${process.pid}.tmp`;
+                let data;
+                try {
+                    data = await resize(input, w, options.quality, format);
+                }
+                catch (err) {
+                    throw new VageError(`Couldn't make a ${format === "avif" ? "AVIF" : "WebP"} copy of ${src}: ${err.message}. Replace the file, or turn off ${format === "avif" ? "images.avif" : "images.optimize"}.`);
+                }
+                fs.writeFileSync(tmp, data);
+                fs.renameSync(tmp, cached);
             }
-            catch (err) {
-                throw new VageError(`Couldn't optimize ${src}: ${err.message}. Replace the file, or turn off images.optimize.`);
-            }
-            fs.writeFileSync(tmp, data);
-            fs.renameSync(tmp, cached);
+            // Label with the file's real width (rotation can change it); publish each width once.
+            const actual = format === "webp" ? (imageSize(cached)?.width ?? w) : (realWidth.get(w) ?? w);
+            if (format === "webp")
+                realWidth.set(w, actual);
+            if (entries.some((e) => e.endsWith(` ${actual}w`)))
+                continue;
+            files.set(`${IMAGE_DIR}/${name}`, cached);
+            entries.push(`/${IMAGE_DIR}/${name} ${actual}w`);
         }
-        // Label with the file's real width (rotation can change it); publish each width once.
-        const actual = imageSize(cached)?.width ?? w;
-        if (entries.some((e) => e.endsWith(` ${actual}w`)))
-            continue;
-        files.set(`${IMAGE_DIR}/${name}`, cached);
-        entries.push(`/${IMAGE_DIR}/${name} ${actual}w`);
+        if (entries.length)
+            srcsets[format] = entries.join(", ");
     }
-    return entries.length ? { srcset: entries.join(", "), files } : undefined;
+    return srcsets.webp ? { srcset: srcsets.webp, avifSrcset: srcsets.avif, files } : undefined;
 }
 /** Image sources used in rendered Markdown, read with an HTML parser (so entities decode like the DOM's). */
 export function contentImageSources(html) {

package/dist/content/sanitize.d.ts

@@ -1,3 +1,9 @@
+/** Optimized copies for one image source: WebP srcset and sizes, plus AVIF when images.avif is on. */
+export interface ImageVariant {
+    srcset: string;
+    sizes: string;
+    avifSrcset?: string;
+}
 /**
  * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
  * contributors or (later) CMS sources, so scripts, event handlers, javascript:
@@ -11,13 +17,7 @@
 export declare function sanitizeHtml(html: string, options?: {
     publicDir?: string;
     inlineStyles?: boolean;
-    variants?: Map<string, {
-        srcset: string;
-        sizes: string;
-    }>;
+    variants?: Map<string, ImageVariant>;
 }): Promise<string>;
 /** For trusted content (`markdown.html: "allow"`): the same image hints, applied through the DOM. */
-export declare function enhanceTrustedHtml(html: string, publicDir: string, variants?: Map<string, {
-    srcset: string;
-    sizes: string;
-}>): Promise<string>;
+export declare function enhanceTrustedHtml(html: string, publicDir: string, variants?: Map<string, ImageVariant>): Promise<string>;

package/dist/content/sanitize.js

@@ -32,15 +32,24 @@ export async function sanitizeHtml(html, options = {}) {
     if (publicDir) {
         purifier.addHook("afterSanitizeAttributes", hook);
     }
+    const config = {
+        // 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"],
+    };
     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"],
-        });
+        if (![...(options.variants?.values() ?? [])].some((v) => v.avifSrcset))
+            return purifier.sanitize(html, config);
+        // AVIF: wrap images in <picture> on DOMPurify's own output tree, then serialize once.
+        // (Editing sanitized HTML as a string and parsing it again could change its meaning.)
+        const fragment = purifier.sanitize(html, { ...config, RETURN_DOM_FRAGMENT: true });
+        addAvifSources(fragment, options.variants);
+        const container = fragment.ownerDocument.createElement("div");
+        container.appendChild(fragment);
+        return container.innerHTML;
     }
     finally {
         if (publicDir)
@@ -53,5 +62,27 @@ export async function enhanceTrustedHtml(html, publicDir, variants) {
     const template = new jsdom.JSDOM("").window.document.createElement("template");
     template.innerHTML = html;
     template.content.querySelectorAll("img").forEach((img, i) => enhanceImage(img, publicDir, i === 0, variants?.get(img.getAttribute("src") ?? "")));
+    if (variants)
+        addAvifSources(template.content, variants);
     return template.innerHTML;
 }
+/**
+ * Offers AVIF first: <picture><source type="image/avif" srcset sizes><img …></picture>.
+ * Browsers without AVIF use the <img> and its WebP srcset. Only images vagejs gave a
+ * srcset are wrapped (an author's own srcset or <picture> is left alone).
+ */
+function addAvifSources(root, variants) {
+    for (const img of [...root.querySelectorAll("img")]) {
+        const v = variants.get(img.getAttribute("src") ?? "");
+        if (!v?.avifSrcset || img.getAttribute("srcset") !== v.srcset || img.parentElement?.nodeName === "PICTURE")
+            continue;
+        const doc = img.ownerDocument;
+        const picture = doc.createElement("picture");
+        const source = doc.createElement("source");
+        source.setAttribute("type", "image/avif");
+        source.setAttribute("srcset", v.avifSrcset);
+        source.setAttribute("sizes", img.getAttribute("sizes") ?? v.sizes);
+        img.replaceWith(picture);
+        picture.append(source, img);
+    }
+}

package/dist/core/config.d.ts

@@ -9,6 +9,7 @@ export declare const configSchema: z.ZodObject<{
         optimize: z.ZodDefault<z.ZodBoolean>;
         widths: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
         quality: z.ZodDefault<z.ZodNumber>;
+        avif: z.ZodDefault<z.ZodBoolean>;
         sizes: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>>;
     markdown: z.ZodDefault<z.ZodObject<{

package/dist/core/config.js

@@ -190,9 +190,10 @@ export const configSchema = z.strictObject({
         optimize: z.boolean().default(false).describe('Make resized WebP copies of images in page content and offer them with srcset. Needs "sharp" in the project (npm install --save-dev sharp).'),
         widths: z.array(z.number().int().min(16).max(8000)).min(1).max(8).default([480, 960, 1600]).describe("Widths to generate (never larger than the original)."),
         quality: z.number().int().min(1).max(100).default(75).describe("WebP quality."),
+        avif: z.boolean().default(false).describe("Also make AVIF copies (usually smaller than WebP, slower to make) and offer both with <picture>: browsers that support AVIF use it, others use WebP."),
         sizes: z.string().regex(/^[^<>"]+$/).default("(max-width: 48rem) 100vw, 48rem").describe('The sizes attribute: how wide images display, so browsers pick the right file.'),
     })
-        .default({ optimize: false, widths: [480, 960, 1600], quality: 75, sizes: "(max-width: 48rem) 100vw, 48rem" }),
+        .default({ optimize: false, widths: [480, 960, 1600], quality: 75, avif: false, sizes: "(max-width: 48rem) 100vw, 48rem" }),
     markdown: z
         .strictObject({
         html: z

package/dist/core/render.js

@@ -23,7 +23,7 @@ export async function renderPage(options) {
             const v = await imageVariants(src, root, site.images, resize);
             if (!v)
                 continue;
-            variants.set(src, { srcset: v.srcset, sizes: site.images.sizes });
+            variants.set(src, { srcset: v.srcset, sizes: site.images.sizes, avifSrcset: v.avifSrcset });
             for (const [k, f] of v.files)
                 assets.set(k, f);
         }

package/dist/deploy/cloudflare-workers.js

@@ -178,7 +178,8 @@ export async function deployCloudflareWorkers(root, options) {
         output = out(upload);
         if (upload.code !== 0) {
             // Only a Worker that doesn't exist yet gets a full deploy (which also attaches routes).
-            if (!/\b10007\b|worker[^\n]*(?:does not exist|not found)/i.test(output))
+            // wrangler 4.152 says "...a new version of a Worker that does not yet exist" (no code).
+            if (!/\b10007\b|worker[^\n]*(?:does not (?:yet )?exist|not found)/i.test(output))
                 return { status: "failure", worker, reason: failReason(upload.code, output) };
             mode = "first-deploy";
             const first = await wrangler("deploy");
@@ -211,7 +212,9 @@ export async function deployCloudflareWorkers(root, options) {
                 return { status: "success", worker, mode, versionId, pageUrl };
             await sleep(3000);
         }
-        return { status: "unconfirmed", worker, mode, versionId, pageUrl, reason: `Deployed, but ${pageUrl} did not respond with 200 yet. Check it in a minute.` };
+        // `site` may not point at this Worker yet (a new domain, or a typo): say where the Worker itself answers.
+        const own = workersDev && workersDev !== pageUrl ? ` The Worker itself is at ${workersDev}. If ${pageUrl} is your own domain, attach it to the Worker (routes or a custom domain in your wrangler config).` : "";
+        return { status: "unconfirmed", worker, mode, versionId, pageUrl, reason: `Deployed, but ${pageUrl} did not respond with 200 yet. Check it in a minute.${own}` };
     }
     finally {
         if (tempDir)

package/dist/deploy/github-pages.d.ts

@@ -31,3 +31,10 @@ export declare function confirmPagesDeployment(cwd: string, sha: string, options
     sleep?: (ms: number) => Promise<void>;
     findRunAttempts?: number;
 }): Promise<DeployStatus>;
+/**
+ * GitHub Pages serves a repository named anything but <owner>.github.io from a subfolder
+ * (https://owner.github.io/repo/). vagejs sites need the root of a domain (links like
+ * /about/ would point outside the site), so that only works with a custom domain.
+ * Returns the problem to show before anything is pushed, or undefined when it's fine.
+ */
+export declare function pagesSubfolderProblem(site: string | undefined, remote: string | undefined): string | undefined;

package/dist/deploy/github-pages.js

@@ -99,3 +99,23 @@ export async function confirmPagesDeployment(cwd, sha, options = {}) {
     const pages = await run("gh", ["api", "repos/{owner}/{repo}/pages", "--jq", ".html_url"], cwd);
     return { status: "success", runUrl, pageUrl: pages.code === 0 ? pages.stdout.trim() || undefined : undefined };
 }
+/**
+ * GitHub Pages serves a repository named anything but <owner>.github.io from a subfolder
+ * (https://owner.github.io/repo/). vagejs sites need the root of a domain (links like
+ * /about/ would point outside the site), so that only works with a custom domain.
+ * Returns the problem to show before anything is pushed, or undefined when it's fine.
+ */
+export function pagesSubfolderProblem(site, remote) {
+    const m = remote && /(?:^|[@/])github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(remote.trim());
+    if (!m || !site)
+        return undefined;
+    const [, owner, repo] = m;
+    if (repo.toLowerCase() === `${owner}.github.io`.toLowerCase())
+        return undefined;
+    if (!/\.github\.io$/i.test(new URL(site).hostname))
+        return undefined; // a custom domain serves the root
+    return (`GitHub Pages would serve this repository at https://${owner.toLowerCase()}.github.io/${repo}/, a subfolder, ` +
+        `but a vagejs site must be served from the root of a domain: links like /about/ would point outside the site. Either:\n` +
+        `  - use your own domain: set site to it in vage.config.ts and add it in the repository under Settings → Pages → Custom domain, or\n` +
+        `  - publish from a repository named ${owner}.github.io (set site to https://${owner.toLowerCase()}.github.io).`);
+}

package/dist/dev/guard.js

@@ -46,7 +46,7 @@ export function allowed(url, publicDir, allowedFiles) {
     if (allowedFiles.has(pathname))
         return true;
     // Optimized images (images.optimize), served from the cache by the dev server.
-    if (/^\/_vage\/img\/[\w-]+\.webp$/.test(pathname))
+    if (/^\/_vage\/img\/[\w-]+\.(webp|avif)$/.test(pathname))
         return true;
     // Generated files (seo.feeds, seo.markdownCopies) never exist on disk in dev. If a real file
     // sits at that path, it's a project source (e.g. /src/pages/about.md): Vite would serve it, so refuse.

package/dist/dev/server.js

@@ -48,12 +48,12 @@ export async function startDevServer(root, options = {}) {
         const urlPath = req.url ?? "/";
         const pathname = urlPath.split(/[?#]/)[0];
         try {
-            const optimized = /^\/_vage\/img\/([\w-]+\.webp)$/.exec(pathname);
+            const optimized = /^\/_vage\/img\/([\w-]+\.(webp|avif))$/.exec(pathname);
             if (optimized) {
                 const file = path.join(cacheDir(root), optimized[1]);
                 if (!fs.existsSync(file))
                     return send(res, 404, plainPage("404 — Not found", `No optimized image at ${pathname}`));
-                res.setHeader("Content-Type", "image/webp");
+                res.setHeader("Content-Type", `image/${optimized[2]}`);
                 return res.end(fs.readFileSync(file));
             }
             const isFeed = /^\/(?:[\w.-]+\/)*feed\.xml$/.test(pathname) && !pathname.includes("..");

package/dist/mcp/server.d.ts

@@ -0,0 +1,23 @@
+/** Published pages and drafts, without writing anything. */
+export declare function listPages(root: string): Promise<{
+    pages: {
+        route: string;
+        source: string;
+        title: string;
+        description: string | undefined;
+        layout: string;
+        noindex: boolean;
+    }[];
+    drafts: string[];
+    errors: import("../core/site.js").PageError[];
+}>;
+/**
+ * `vage mcp`: an MCP server over stdio for the project at `root`. Every tool is
+ * read-only; approving links and deploying stay with people, through the CLI.
+ * stdout carries the protocol, so anything else that prints goes to stderr.
+ */
+export declare function startMcpServer(root: string, options: {
+    version: string;
+    info: () => unknown;
+    transport?: unknown;
+}): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,80 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { check } from "../checks/check.js";
+import { linkStatus } from "../checks/links.js";
+import { VageError } from "../core/errors.js";
+import { createBuildLoader } from "../core/loader.js";
+import { renderSite } from "../core/site.js";
+/** The MCP SDK is optional: only people who run `vage mcp` install it. */
+const SDK = "@modelcontextprotocol/sdk";
+const INSTALL = `vage mcp needs the "${SDK}" package. Install it in your project with: npm install --save-dev ${SDK}`;
+/** Loads the SDK from the project first, then from wherever vagejs itself is installed. */
+async function loadSdk(root) {
+    for (const from of [path.join(root, "package.json"), import.meta.url]) {
+        try {
+            const req = createRequire(from);
+            const mcp = await import(pathToFileURL(req.resolve(`${SDK}/server/mcp.js`)).href);
+            const stdio = await import(pathToFileURL(req.resolve(`${SDK}/server/stdio.js`)).href);
+            return { McpServer: mcp.McpServer, StdioServerTransport: stdio.StdioServerTransport };
+        }
+        catch {
+            // try the next location
+        }
+    }
+    throw new VageError(INSTALL);
+}
+/** Published pages and drafts, without writing anything. */
+export async function listPages(root) {
+    const loader = await createBuildLoader(root);
+    try {
+        const model = await renderSite(root, loader.load, { collectErrors: true });
+        return {
+            pages: model.pages.map((p) => ({
+                route: p.route,
+                source: p.source,
+                title: p.frontmatter.title,
+                description: p.frontmatter.description,
+                layout: p.frontmatter.layout ?? "default",
+                noindex: Boolean(p.meta.noindex),
+            })),
+            drafts: model.skippedDrafts,
+            errors: model.pageErrors,
+        };
+    }
+    finally {
+        await loader.close();
+    }
+}
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+/** Runs a tool; a failure (a broken layout, an invalid config) becomes a readable error result, without terminal colors. */
+const tool = (fn) => async () => {
+    try {
+        return text(await fn());
+    }
+    catch (err) {
+        // eslint-disable-next-line no-control-regex
+        const message = String(err?.message ?? err).replace(/\u001b\[[0-9;]*m/g, "");
+        return { isError: true, content: [{ type: "text", text: message }] };
+    }
+};
+/**
+ * `vage mcp`: an MCP server over stdio for the project at `root`. Every tool is
+ * read-only; approving links and deploying stay with people, through the CLI.
+ * stdout carries the protocol, so anything else that prints goes to stderr.
+ */
+export async function startMcpServer(root, options) {
+    root = path.resolve(root);
+    const sdk = await loadSdk(root);
+    if (!options.transport)
+        console.log = console.info = (...args) => console.error(...args);
+    const server = new sdk.McpServer({ name: "vagejs", version: options.version }, {
+        instructions: "Tools for a vagejs website project. Use vage_info for commands, settings and page fields; vage_check after every change (fix every error it reports; each finding names the file); vage_pages to see what exists; vage_links for outbound domains. Never approve link domains or deploy without the site owner: those stay CLI commands (npx vage links approve, npx vage deploy).",
+    });
+    server.registerTool("vage_info", { title: "Describe vagejs", description: "Commands, configuration options and page frontmatter fields, with their JSON Schemas (the same as `vage info --json`).", annotations: READ_ONLY }, tool(async () => options.info()));
+    server.registerTool("vage_check", { title: "Check the site", description: "Checks every page for broken links, missing titles and descriptions, structured data, accessibility basics and unapproved outbound links (the same as `vage check --json`). Writes nothing.", annotations: READ_ONLY }, tool(() => check(root)));
+    server.registerTool("vage_pages", { title: "List pages", description: "Every published page (route, source file, title, description, layout, noindex), the drafts that are skipped, and pages that fail to render.", annotations: READ_ONLY }, tool(() => listPages(root)));
+    server.registerTool("vage_links", { title: "List outbound domains", description: "External domains the site links to, which pages link there, and whether each is approved in links.lock.json. Only the site owner approves new domains.", annotations: READ_ONLY }, tool(() => linkStatus(root)));
+    await server.connect(options.transport ?? new sdk.StdioServerTransport());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vagejs",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A free static site generator for AI website development: Markdown pages with built-in SEO, llms.txt, checks, spam protection and safe deploys.",
   "keywords": [
     "static-site-generator",
@@ -57,6 +57,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/jsdom": "^28.0.3",
     "@types/node": "^26.6.5",
     "@types/turndown": "^5.0.6",

package/templates/starter/AGENTS.md

@@ -20,14 +20,16 @@ Run `npm run check` after every change and fix all errors before finishing.
 
 `npx vage info --json` prints every command and option plus JSON Schemas for `vage.config.ts` and page frontmatter. Prefer it over guessing.
 
+**MCP server (optional):** `npx vage mcp` runs an MCP server over stdio with four read-only tools: `vage_info`, `vage_check`, `vage_pages` and `vage_links`. It needs `npm install --save-dev @modelcontextprotocol/sdk` in the project. For Claude Code, run in the project folder: `claude mcp add --transport stdio --scope project vagejs -- npx -p vagejs vage mcp` (saved in `.mcp.json`). Other assistants: `{ "mcpServers": { "vagejs": { "command": "npx", "args": ["-p", "vagejs", "vage", "mcp", "--root", "/absolute/path/to/the/site"] } } }`. `-p vagejs` makes npx run the vagejs installed in the project, and never a different package that happens to be called `vage`. Approving link domains and deploying are not MCP tools; they stay CLI commands the site owner approves. Layouts must not write to `process.stdout` directly: in MCP mode stdout carries the protocol (vagejs moves `console.log` to stderr).
+
 ## Recipes
 
-- **Add a page:** create `src/pages/<slug>.md` with `title` and `description` frontmatter; link to it as `/<slug>/` (trailing slash).
-- **Add a blog post:** `src/pages/blog/<slug>.md`; it appears on `/blog/` automatically (`src/layouts/blog.ts`). For Article data add `type: article`, plus `author` / `datePublished` only if the owner provided them.
+- **Add a page:** `npx vage new page <slug>` (folders allowed: `docs/setup`; options `--title`, `--description`) creates `src/pages/<slug>.md` as a draft with valid frontmatter, or create the file yourself with `title` and `description`. Link to it as `/<slug>/` (trailing slash). Remove `draft: true` when it's ready, then run `npm run check`.
+- **Add a blog post:** `npx vage new post "<Title>"` creates `src/pages/blog/<slug>.md` as a draft with `type: article` and today's `datePublished` (`--date`, `--under <folder>`, and `--author` only with a real name from the owner). It appears on `/blog/` automatically (`src/layouts/blog.ts`) once `draft: true` is removed.
 - **Add a layout:** `src/layouts/<name>.ts`, then `layout: <name>` in frontmatter. Keep `<html lang>`, one `<title>` and `</head>`.
 - **List pages (blog index, "latest posts", a sidebar):** in a layout, `collection(pages, { under: "/blog/", sort: "date" })` from `vagejs`. Never keep a hand-written list of pages.
 - **Give a layout its own frontmatter fields:** `export const frontmatter = z.object({ ... })` in the layout (`import { z } from "vagejs"`). Pages using it are then checked strictly: unknown or mistyped fields fail the build.
-- **Add an image:** put it in `public/images/` and write `![Describe the image](/images/name.jpg)`. Width and height are filled in from the file; write real alt text. For resized WebP copies, the owner can turn on `images: { optimize: true }` (needs `npm install --save-dev sharp`). Only images in page content are optimized, not images a layout writes.
+- **Add an image:** put it in `public/images/` and write `![Describe the image](/images/name.jpg)`. Width and height are filled in from the file; write real alt text. For resized WebP copies, the owner can turn on `images: { optimize: true }` (needs `npm install --save-dev sharp`), and `avif: true` for AVIF copies offered first through `<picture>`. Only images in page content are optimized, not images a layout writes.
 - **Order a menu or sidebar:** set `order:` (lower first) and optionally a short `navTitle:` in each page's frontmatter (shown as `p.label`), then build the menu in a layout with `tree(pages, "/docs/")`. For previous/next links in the same order use `neighbors(flatten(tree(pages, "/docs/")), page.route)`. For a flat section, `collection(pages, { under: "/docs/", sort: "order", includeIndex: true })` works too. `breadcrumbs(pages, page.route)` gives the trail from the home page.
 - **Add an RSS feed for the blog:** `seo: { feeds: [{ under: "/blog/" }] }` in `vage.config.ts` writes `/blog/feed.xml`, newest `datePublished` first (undated posts last, without a date).
 - **Help AI tools read the site:** `seo: { markdownCopies: true }` publishes a Markdown copy of every listed page (`/docs/cli/` becomes `/docs/cli.md`), converted from the page's `<main>`, so it contains exactly what the page shows (including content a layout builds from frontmatter), and `llms.txt` links to them. In layouts, add `data-vage-copy="skip"` to repeated extras such as share links or a call to action to leave them out of the copy. On Cloudflare, each copy gets a canonical `Link` header pointing to its page. `seo: { lastmod: "git" }` dates the sitemap from git history (needs full history in CI: `fetch-depth: 0`).
@@ -144,7 +146,9 @@ Always ask the site owner before publishing or deploying. Show them the plan fir
 
 After deploying, `npx vage indexnow --changed-since HEAD~1` (needs `integrations.indexNow.key`) tells IndexNow search engines about changed pages. It's a hint, not a guarantee of indexing; ask the owner first.
 
-GitHub Pages needs a custom domain or a `<user>.github.io` repository, because vagejs does not support base paths yet.
+GitHub Pages needs a custom domain or a `<user>.github.io` repository, because vagejs does not support base paths yet; `vage deploy` stops before pushing when the site would land in a subfolder.
+
+Other static hosts (Vercel, Netlify and the like) work without a vagejs deploy command: build command `npm run build`, output folder `dist`, no framework preset. Config redirects become small forwarding pages there, and the `_headers` security headers apply only on Cloudflare.
 `.github/workflows/ci.yml` runs check, build and audit on every push and PR, and uploads `dist/` as a downloadable preview artifact.
 
 ## Analytics and search reports
@@ -164,7 +168,7 @@ Off unless configured in `vage.config.ts` under `integrations`. Ask the site own
 
 ## Not implemented yet
 
-Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, AVIF images. Do not use or document them as available. A passing `check` does not guarantee indexing, rankings or AI citations.
+Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths. Do not use or document them as available. A passing `check` does not guarantee indexing, rankings or AI citations.
 
 ## Favicon
 

package/templates/starter/package.json

@@ -12,6 +12,6 @@
     "preview": "vage preview"
   },
   "devDependencies": {
-    "vagejs": "^0.3.4"
+    "vagejs": "^0.4.0"
   }
 }

package/templates/starter/vage.config.ts

@@ -10,8 +10,8 @@ export default defineConfig({
   seo: {
     robots: {
       // AI crawler policy is your decision; unset means the "*" rules apply.
-      // aiTraining: "disallow", // GPTBot, ClaudeBot, Google-Extended
-      // aiSearch: "allow",      // OAI-SearchBot, Claude-SearchBot
+      // aiTraining: "disallow", // GPTBot, ClaudeBot, Google-Extended, Applebot-Extended
+      // aiSearch: "allow",      // OAI-SearchBot, Claude-SearchBot, PerplexityBot
     },
     sitemap: true,
     llmsTxt: { full: false },