vagejs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vagejs.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/brand/vagejs-logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/brand/vagejs-logo.svg" alt="vagejs" width="320">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/vagejs"><img src="https://img.shields.io/npm/v/vagejs?color=4F46E5&label=npm" alt="npm version"></a>
+  <a href="https://github.com/agevenkat/vagejs/actions/workflows/ci.yml"><img src="https://github.com/agevenkat/vagejs/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/vagejs?color=2E2A8C" alt="MIT license"></a>
+</p>
+
+# 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).**
+
+- **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.
+
+## Quick start
+
+Requires **Node.js 22.12 or newer**.
+
+```bash
+npm create vagejs@latest my-site
+cd my-site
+npm install
+npm run dev
+```
+
+Open the URL it prints. Edit `src/pages/index.md` and the browser reloads.
+
+## Using vagejs
+
+### Project layout
+
+```text
+my-site/
+├── src/
+│   ├── pages/          # every .md file is a page
+│   │   ├── index.md    # → /
+│   │   ├── about.md    # → /about/
+│   │   └── blog/
+│   │       └── first-post.md   # → /blog/first-post/
+│   └── layouts/
+│       └── default.ts  # HTML around each page
+├── public/             # copied to the site as-is (favicons, images)
+├── vage.config.ts      # site settings
+└── AGENTS.md           # instructions for AI coding agents
+```
+
+### Write a page
+
+```markdown
+---
+title: Pricing
+description: Plans and prices.
+---
+
+# Pricing
+
+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.
+
+### Write a layout
+
+Layouts are TypeScript functions. The `html` template tag escapes every value for you; `raw()` inserts trusted HTML such as the rendered page. (Escaping doesn't check URLs, so validate link targets that come from frontmatter.) `pages` lists every published page, and `collection()` picks and sorts them:
+
+```ts
+import { collection, html, raw, z, type Layout } from "vagejs";
+
+// Optional: fields this layout accepts. Pages using it are checked strictly, so typos fail the build.
+export const frontmatter = z.object({ intro: z.string().optional() });
+
+const layout: Layout = ({ content, page, site, pages }) => html`<!doctype html>
+<html lang="${site.lang}">
+  <head><title>${page.title}</title></head>
+  <body>
+    <main>${raw(content)}</main>
+    <h2>Latest posts</h2>
+    <ul>${collection(pages, { under: "/blog/", sort: "date", limit: 5 }).map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>
+  </body>
+</html>`;
+
+export default layout;
+```
+
+### Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run dev` | Dev server with live reload |
+| `npm run check` | Links, SEO, structured data and basic accessibility; writes nothing |
+| `npm run build` | Static site in `dist/`, plus `robots.txt`, `sitemap.xml`, `llms.txt` |
+| `npm run audit` | Page-weight budgets and automated accessibility (`-- --lighthouse` adds Lighthouse) |
+| `npm run preview` | Serves `dist/` locally, the way a static host would |
+
+Add `--json` to `npx vage build`, `check` or `audit` for machine-readable output. Failures exit with code 1.
+
+### Configure the site
+
+`vage.config.ts`:
+
+```ts
+import { defineConfig } from "vagejs";
+
+export default defineConfig({
+  site: "https://example.com", // your real domain (used for canonical URLs and the sitemap)
+  title: "My Website",
+  description: "What this site is about.",
+  seo: {
+    robots: { aiTraining: "disallow" }, // optional: block AI training crawlers, keep search
+    llmsTxt: { full: false },
+  },
+  redirects: { "/old-page/": "/new-page/" },
+});
+```
+
+Unknown keys are an error, so typos don't silently do nothing. `npx vage info --json` prints the full schema.
+
+### Deploy
+
+```bash
+npx vage deploy:github --remote https://github.com/you/site.git   # check, build, safe commit + push (asks first)
+npx vage deploy                                                  # GitHub Pages via Actions
+npx vage deploy --target cloudflare-workers --project my-site    # Cloudflare Workers: new version, no downtime
+npx vage deploy --target cloudflare-pages --project my-site      # older Cloudflare Pages projects
+```
+
+Every deploy shows its plan and asks for confirmation (`--dry-run` to preview, `--yes` to skip). It reports success only after the host confirms.
+
+Cloudflare now creates new static sites as Workers, so use `cloudflare-workers` for new projects. For a custom domain, add a `wrangler.jsonc` with your `routes`; vagejs uses it and switches versions without re-attaching domains, so the site stays up during deploys.
+
+### Analytics, Search Console and audits of live pages
+
+Optional, and off until configured: GA4 or Google Tag Manager (consent denied by default), Plausible, Microsoft Clarity, IndexNow. `vage connect gsc|ga4` adds read-only Search Console and GA4 reports, and `vage audit --url https://your-site` runs PageSpeed and CrUX with **your own** Google API key. Details are in the generated `AGENTS.md`.
+
+## Updating
+
+vagejs follows semver. While it's 0.x, a minor version (0.1 → 0.2) may include breaking changes, so read the release notes before moving up a minor version.
+
+```bash
+npm outdated vagejs           # see what's available
+npm update vagejs             # latest patch in your range (with ^0.2.0: any 0.2.x)
+npm install vagejs@latest     # move to the newest version, including a new minor
+npx vage --version            # confirm
+npx vage check && npx vage build
+```
+
+If your config pins the rule pack (`guidelines: { rulePack: "…" }`), a build after an update that ships new provider rules stops with a message. Review them with `npx vage guidelines`, then update the pin. New projects always use the latest version through `npm create vagejs@latest`.
+
+## Use with AI coding agents
+
+Every site includes `AGENTS.md` (conventions, recipes, definition of done) and `CLAUDE.md` (imports `AGENTS.md`). Agents can discover the API instead of guessing:
+
+```bash
+npx vage info --json    # commands, options, config and frontmatter JSON Schemas
+npx vage check --json   # findings with file, rule and fix hints
+```
+
+## Command reference
+
+```bash
+vage create <dir> [--vage-spec <spec>] [--json]   # scaffold a Markdown site
+vage dev      [--root .] [--port N] [--host]      # dev server with live reload
+vage build    [--root .] [--json]                 # static build into dist/ (+ robots.txt, sitemap.xml, llms.txt)
+vage check    [--root .] [--json] [--strict]      # SEO, links, JSON-LD, basic a11y; writes nothing
+vage audit    [--root .] [--lighthouse] [--url U] [--strategy mobile|desktop|both] [--strict] [--json]
+                                                  # budgets + axe a11y; optional Lighthouse; PageSpeed/CrUX for deployed URLs
+vage preview  [--root .] [--port N] [--host]      # serve dist/ locally
+vage deploy:github [--remote URL] [--branch B] [-m MSG] [--dry-run] [--yes] [--json]   # check, build, safe commit + push (asks first)
+vage deploy        [--remote URL] [--no-wait] [--dry-run] [--yes] # GitHub Pages via Actions; confirms with GitHub
+vage deploy --target cloudflare-workers [--project NAME]          # new Worker version at 100%; custom domains stay up
+vage deploy --target cloudflare-pages --project NAME [--branch B] # Wrangler upload; preview URL per branch
+vage indexnow --changed-since REF | --urls … | --all              # IndexNow URL notification (asks first)
+vage connect gsc|ga4 / vage disconnect google      # read-only Google OAuth (PKCE, loopback); token outside the repo
+vage connect pagespeed|crux / vage disconnect …   # save your own Google API key for audit --url (outside the repo)
+vage report search|analytics [--days N] [--json]  # Search Console top queries/pages; GA4 top pages
+vage guidelines [--json]                          # rule pack: provider facts in use, sources, changelog
+vage info     [--json]                            # commands + config/frontmatter JSON Schemas for agents
+```
+
+## Planned, not implemented
+
+Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server, image resizing and WebP/AVIF conversion.
+
+## Security
+
+Page content is sanitized, dev/preview servers serve only what a site needs, and Cloudflare deploys get security headers with a computed Content-Security-Policy. Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
+
+### Protection against spam injection
+
+A static site has no admin panel, database or plugins to break into, so attackers go after your content, your repository or your host instead, usually to plant hidden links and spam pages. vagejs checks for that on every build:
+
+| Protection | What it does |
+| --- | --- |
+| Outbound link lock | `links.lock.json` lists the domains your site may link to. A link to any other domain fails `vage check` (and so every deploy) until you approve it with `vage links approve <domain>`. It covers links, SVG links, canonical and `og:url`, meta refresh, iframes and forms. With `security.outboundLinks: "require"` (the default for new sites), deleting the file is an error too. |
+| No hidden links | Inline styles, SVG `xlink:href` and legacy tags like `<font>` and `<marquee>` are stripped from page content, and `vage check` fails on external links hidden with CSS, `aria-hidden`, zero-size SVG or no visible content, in content and layouts. |
+| Spam words | `vage check` warns about common injected-spam terms (casino, pharmacy, payday loans…). |
+| Live-site verification | `vage verify` compares the live site with your files: links and other targets, scripts, event handlers, JSON-LD, text (spam words are errors), `robots.txt` and sitemap pages. It also looks at every page as Googlebot, to catch spam shown only to search engines. New sites include a daily GitHub Actions check (opt in with the `VAGE_VERIFY_URL` variable). |
+| Supply chain | New sites run `npm audit` in CI and get Dependabot updates. |
+
+```bash
+npx vage links                    # list external domains: approved or NEW
+npx vage links approve github.com # approve one (asks first)
+npx vage verify                   # compare the live site with your files
+```
+
+Also protect the accounts around the site: two-factor authentication on GitHub, npm, your host and your domain registrar; branch protection on `main`; and Google Search Console alerts for security issues.
+
+## Contributing
+
+```bash
+npm install
+npm run typecheck
+npm test            # unit + integration (dev server, preview, build)
+npm run test:e2e    # pack -> create -> npm install/ci -> build (needs npm registry or cache)
+```
+
+Design decisions: [docs/DECISIONS.md](docs/DECISIONS.md). Provider rules and how they're monitored: [docs/GUIDELINES.md](docs/GUIDELINES.md). Releasing: [docs/RELEASING.md](docs/RELEASING.md).
+
+## Brand assets
+
+- `assets/brand/vagejs-icon.svg`: the icon, as received (with C2PA content credentials).
+- `assets/brand/vagejs-logo.svg` and `vagejs-logo-dark.svg`: the wordmark for light and dark backgrounds, with **Space Grotesk Bold embedded** (a 1.6 KB WOFF2 subset of the glyphs used), so it renders the same without the font installed. Space Grotesk is © 2020 The Space Grotesk Project Authors, under the SIL Open Font License 1.1 (`assets/brand/fonts/OFL.txt`). Editing the file invalidated its C2PA signature, so that block was removed. The dark variant only changes the text colors (`#F4F5FA` and `#A5B4FC`).
+- New sites get `favicon.svg`, `favicon.ico` (16/32/48) and `apple-touch-icon.png` (180) in `public/`.
+
+Regenerate (maintainer tools; need Chrome, and Python with `fonttools` and `brotli`):
+
+```bash
+node scripts/brand/favicons.mjs templates/starter/public/favicon.svg templates/starter/public
+python -I scripts/brand/embed-logo-font.py "SpaceGrotesk[wght].ttf" <original-logo.svg> assets/brand/vagejs-logo.svg
+```
+
+## License
+
+MIT © 2026 vagejs.com

package/dist/audit/a11y.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "../checks/check.js";
+export interface A11yPageResult {
+    route: string;
+    findings: Finding[];
+    /** Rules axe could not decide without a real browser (e.g. color contrast). */
+    needsReview: string[];
+}
+/**
+ * Runs axe-core against static HTML in jsdom. No page scripts run and nothing
+ * is fetched, so layout-dependent rules (color contrast, target size) come back
+ * as "needs review"; use Lighthouse (`vage audit --lighthouse`) for those.
+ */
+export declare function auditAccessibility(route: string, html: string): Promise<A11yPageResult>;

package/dist/audit/a11y.js

@@ -0,0 +1,33 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { JSDOM, VirtualConsole } from "jsdom";
+const axeSource = fs.readFileSync(createRequire(import.meta.url).resolve("axe-core/axe.min.js"), "utf8");
+/**
+ * Runs axe-core against static HTML in jsdom. No page scripts run and nothing
+ * is fetched, so layout-dependent rules (color contrast, target size) come back
+ * as "needs review"; use Lighthouse (`vage audit --lighthouse`) for those.
+ */
+export async function auditAccessibility(route, html) {
+    // A detached console keeps jsdom's "not implemented" notices (e.g. canvas, probed by axe) out of the output.
+    const dom = new JSDOM(html, { runScripts: "outside-only", pretendToBeVisual: true, virtualConsole: new VirtualConsole() });
+    try {
+        const window = dom.window;
+        window.eval(axeSource);
+        const results = await window.axe.run(window.document, { resultTypes: ["violations", "incomplete"] });
+        const findings = results.violations.map((v) => ({
+            rule: `a11y:${v.id}`,
+            // critical/serious block users; moderate/minor still matter but are warnings.
+            severity: v.impact === "critical" || v.impact === "serious" ? "error" : "warning",
+            page: route,
+            message: `${v.help} (${v.nodes.length} element${v.nodes.length === 1 ? "" : "s"}: ${v.nodes
+                .slice(0, 3)
+                .map((n) => n.target.join(" "))
+                .join(", ")})`,
+            docs: v.helpUrl,
+        }));
+        return { route, findings, needsReview: results.incomplete.map((r) => r.id) };
+    }
+    finally {
+        dom.window.close();
+    }
+}

package/dist/audit/audit.d.ts

@@ -0,0 +1,31 @@
+import type { Finding } from "../checks/check.js";
+import { type ApiKeyName } from "../integrations/api-keys.js";
+import { type PageWeight } from "./budgets.js";
+import { type FieldReport, type LabReport, type RemoteOptions, type Strategy } from "./remote.js";
+export interface AuditOptions {
+    /** Fail on warnings too (budgets, lab scores, API failures). */
+    strict?: boolean;
+    /** Run Lighthouse locally (also enabled by performance.lighthouse.enabled). */
+    lighthouse?: boolean;
+    /** Audit a deployed URL with PageSpeed Insights + CrUX instead of the local build. */
+    url?: string;
+    strategies?: Strategy[];
+    env?: Record<string, string | undefined>;
+    remote?: RemoteOptions;
+    /** Asks the user for their own key when none is configured (interactive CLI only). */
+    askForKey?: (name: ApiKeyName) => Promise<string | undefined>;
+}
+export interface AuditResult {
+    ok: boolean;
+    errors: number;
+    warnings: number;
+    target: string;
+    findings: Finding[];
+    pages: PageWeight[];
+    /** axe rules that need a real browser or manual review. */
+    needsReview: string[];
+    lab: LabReport[];
+    field: FieldReport[];
+    notes: string[];
+}
+export declare function audit(root: string, options?: AuditOptions): Promise<AuditResult>;

package/dist/audit/audit.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import path from "node:path";
+import { buildSite } from "../core/build.js";
+import { loadProjectConfig } from "../core/project-config.js";
+import { missingKeyMessage, resolveApiKey } from "../integrations/api-keys.js";
+import { VageError } from "../core/errors.js";
+import { startPreviewServer } from "../dev/preview.js";
+import { auditAccessibility } from "./a11y.js";
+import { budgetFindings, measurePages } from "./budgets.js";
+import { runLighthouse } from "./lighthouse.js";
+import { cruxField, pageSpeed } from "./remote.js";
+import { LAB_VS_FIELD, VITALS } from "./vitals.js";
+export async function audit(root, options = {}) {
+    root = path.resolve(root);
+    const strategies = options.strategies ?? ["mobile", "desktop"];
+    const partial = options.url ? await auditUrl(root, options.url, strategies, options) : await auditLocal(root, strategies, options);
+    const errors = partial.findings.filter((f) => f.severity === "error").length;
+    const warnings = partial.findings.length - errors;
+    if (partial.lab.length || partial.field.length)
+        partial.notes.push(LAB_VS_FIELD);
+    return { ...partial, ok: errors === 0 && (!options.strict || warnings === 0), errors, warnings };
+}
+async function auditLocal(root, strategies, options) {
+    const { result, model } = await buildSite(root);
+    const site = model.site;
+    const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
+    const weights = measurePages(result.outDir, pages, site.site);
+    const findings = budgetFindings(weights, site.performance.budgets);
+    const notes = ["Sizes are uncompressed bytes of local files; transfer size depends on your host's compression."];
+    const needsReview = new Map();
+    for (const page of pages) {
+        const html = fs.readFileSync(path.join(result.outDir, page.outFile), "utf8");
+        const a11y = await auditAccessibility(page.route, html);
+        findings.push(...a11y.findings.map((f) => ({ ...f, source: page.source })));
+        for (const rule of a11y.needsReview)
+            needsReview.set(rule, (needsReview.get(rule) ?? 0) + 1);
+    }
+    if (needsReview.size) {
+        const list = [...needsReview].map(([rule, n]) => `${rule} (${n} page${n === 1 ? "" : "s"})`).join(", ");
+        notes.push(`Automated checks could not decide: ${list}. Review manually or run with --lighthouse (real browser).`);
+    }
+    for (const w of weights.filter((w) => w.hasJavaScript)) {
+        notes.push(`${w.route} ships client-side JavaScript (${(w.bytes.javascript / 1024).toFixed(1)} KB local). Static pages usually need none.`);
+    }
+    const lab = [];
+    if (options.lighthouse || site.performance.lighthouse.enabled) {
+        const routes = site.performance.lighthouse.pages;
+        const known = new Set(model.pages.map((p) => p.route));
+        const unknown = routes.filter((r) => !known.has(r));
+        if (unknown.length)
+            throw new VageError(`performance.lighthouse.pages lists routes that are not published: ${unknown.join(", ")}`);
+        const server = await startPreviewServer(root, {});
+        try {
+            const base = server.resolvedUrls.local[0].replace(/\/$/, "");
+            lab.push(...(await runLighthouse(root, routes.map((r) => base + r), strategies)));
+        }
+        finally {
+            await server.close();
+        }
+        notes.push("Local Lighthouse runs on your machine; scores differ from PageSpeed Insights and from real users.");
+        findings.push(...scoreFindings(lab, site));
+    }
+    return { target: result.outDir, findings, pages: weights, needsReview: [...needsReview.keys()], lab, field: [], notes };
+}
+async function auditUrl(root, url, strategies, options) {
+    if (!/^https?:\/\//.test(url))
+        throw new VageError(`--url must be an absolute http(s) URL, got "${url}".`);
+    const env = options.env ?? process.env;
+    const site = await loadProjectConfig(path.resolve(root));
+    const findings = [];
+    const notes = [];
+    const lab = [];
+    const field = [];
+    const failure = (rule, err) => findings.push({ rule, severity: options.strict ? "error" : "warning", message: err.message });
+    // Always the user's own keys: never a shared or built-in key, and no keyless fallback.
+    const keyFor = async (name) => resolveApiKey(name, env) ?? (await options.askForKey?.(name));
+    const psiKey = await keyFor("pagespeed");
+    if (!psiKey) {
+        findings.push({ rule: "pagespeed", severity: "error", message: missingKeyMessage("pagespeed") });
+    }
+    else {
+        for (const strategy of strategies) {
+            try {
+                lab.push(await pageSpeed(url, strategy, psiKey, options.remote));
+            }
+            catch (err) {
+                failure("pagespeed", err);
+            }
+        }
+    }
+    findings.push(...scoreFindings(lab, site));
+    // One Google Cloud key can enable both APIs, so the PageSpeed key is tried for CrUX too.
+    const cruxKey = resolveApiKey("crux", env) ?? psiKey ?? (await options.askForKey?.("crux"));
+    if (!cruxKey) {
+        notes.push(`No field data. ${missingKeyMessage("crux")}`);
+    }
+    else {
+        for (const strategy of strategies) {
+            try {
+                const report = await cruxField(url, strategy, cruxKey, options.remote);
+                if (!report) {
+                    notes.push(`No CrUX field data for ${url} or its origin (${strategy}); the site may not have enough Chrome traffic.`);
+                    continue;
+                }
+                field.push(report);
+                for (const [name, m] of Object.entries(report.metrics)) {
+                    if (m.rating !== "good") {
+                        const t = VITALS[name];
+                        findings.push({
+                            rule: "field-vitals",
+                            severity: "warning",
+                            message: `${t.label} p75 is ${m.p75}${t.unit} (${m.rating}; good is ≤ ${t.good}${t.unit}) for ${report.formFactor} (${report.scope}-level, real users).`,
+                            docs: "https://web.dev/articles/vitals",
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                failure("crux", err);
+            }
+        }
+    }
+    return { target: url, findings, pages: [], needsReview: [], lab, field, notes };
+}
+function scoreFindings(lab, site) {
+    const b = site.performance.budgets;
+    const budgets = { performance: b.performance, accessibility: b.accessibility, seo: b.seo, "best-practices": b.bestPractices };
+    const findings = [];
+    for (const r of lab) {
+        for (const [category, min] of Object.entries(budgets)) {
+            const score = r.scores[category];
+            if (score !== null && score < min) {
+                findings.push({
+                    rule: "lab-score",
+                    severity: "warning",
+                    page: r.url,
+                    message: `${category} ${score} < budget ${min} (${r.strategy}, ${r.source}, lab).`,
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/audit/budgets.d.ts

@@ -0,0 +1,22 @@
+import type { SiteConfig } from "../core/config.js";
+import type { Finding } from "../checks/check.js";
+export type ResourceKind = "html" | "javascript" | "css" | "image" | "font";
+export interface PageWeight {
+    route: string;
+    /** Uncompressed bytes of local files by kind. Transfer size depends on the host's compression. */
+    bytes: Record<ResourceKind, number>;
+    total: number;
+    /** Requests including the HTML document and external resources. */
+    requests: number;
+    /** Resources on other origins: counted as requests, size not measured. */
+    external: string[];
+    /** True when the page ships executable JavaScript. */
+    hasJavaScript: boolean;
+}
+/** Measures each built page and the local resources it references. */
+export declare function measurePages(outDir: string, pages: {
+    route: string;
+    outFile: string;
+}[], site?: string): PageWeight[];
+export declare function budgetFindings(weights: PageWeight[], budgets: SiteConfig["performance"]["budgets"]): Finding[];
+export declare function kbText(bytes: number): string;

package/dist/audit/budgets.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "node-html-parser";
+const FONT = /\.(woff2?|ttf|otf|eot)$/i;
+const IMAGE = /\.(png|jpe?g|gif|webp|avif|svg|ico)$/i;
+/** Measures each built page and the local resources it references. */
+export function measurePages(outDir, pages, site) {
+    return pages.map(({ route, outFile }) => {
+        const html = fs.readFileSync(path.join(outDir, outFile), "utf8");
+        const doc = parse(html);
+        const weight = {
+            route,
+            bytes: { html: Buffer.byteLength(html), javascript: 0, css: 0, image: 0, font: 0 },
+            total: 0,
+            requests: 1,
+            external: [],
+            hasJavaScript: false,
+        };
+        const seen = new Set();
+        const add = (ref, kind, base) => {
+            if (!ref || ref.startsWith("data:"))
+                return;
+            const url = new URL(ref, `http://local.invalid${base}`);
+            const key = url.href;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            weight.requests++;
+            const local = url.host === "local.invalid" || (site !== undefined && url.origin === site);
+            if (!local)
+                return weight.external.push(url.href);
+            let rel;
+            try {
+                rel = decodeURIComponent(url.pathname);
+            }
+            catch {
+                return; // malformed URLs are reported by `vage check`
+            }
+            const file = path.resolve(outDir, `.${rel}`);
+            if (!file.startsWith(outDir + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile())
+                return; // missing assets are reported by `vage check`
+            weight.bytes[kind] += fs.statSync(file).size;
+            if (kind === "css") {
+                // Fonts and images referenced from stylesheets load with the page too.
+                for (const m of fs.readFileSync(file, "utf8").matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)/g)) {
+                    const inner = m[1];
+                    if (FONT.test(inner))
+                        add(new URL(inner, url).pathname, "font", "/");
+                    else if (IMAGE.test(inner))
+                        add(new URL(inner, url).pathname, "image", "/");
+                }
+            }
+        };
+        for (const s of doc.querySelectorAll("script")) {
+            const type = s.getAttribute("type");
+            if (type && !/^(module|text\/javascript|application\/javascript)$/i.test(type))
+                continue; // e.g. JSON-LD
+            weight.hasJavaScript = true;
+            if (s.getAttribute("src"))
+                add(s.getAttribute("src"), "javascript", route);
+        }
+        for (const l of doc.querySelectorAll('link[rel="stylesheet"]'))
+            add(l.getAttribute("href"), "css", route);
+        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);
+        weight.total = Object.values(weight.bytes).reduce((a, b) => a + b, 0);
+        return weight;
+    });
+}
+const BUDGET_KEYS = [
+    ["javascriptKb", "javascript"],
+    ["cssKb", "css"],
+    ["imageKb", "image"],
+    ["fontKb", "font"],
+    ["totalKb", "total"],
+];
+export function budgetFindings(weights, budgets) {
+    const findings = [];
+    for (const w of weights) {
+        for (const [key, kind] of BUDGET_KEYS) {
+            const bytes = kind === "total" ? w.total : w.bytes[kind];
+            if (bytes > budgets[key] * 1024) {
+                findings.push({
+                    rule: "budget",
+                    severity: "warning",
+                    page: w.route,
+                    message: `${kind} is ${kbText(bytes)}, over the ${budgets[key]} KB budget (performance.budgets.${key}).`,
+                });
+            }
+        }
+        if (w.requests > budgets.requests) {
+            findings.push({
+                rule: "budget",
+                severity: "warning",
+                page: w.route,
+                message: `${w.requests} requests, over the budget of ${budgets.requests} (performance.budgets.requests).`,
+            });
+        }
+    }
+    return findings;
+}
+export function kbText(bytes) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+}

package/dist/audit/lighthouse.d.ts

@@ -0,0 +1,3 @@
+import { type LabReport, type Strategy } from "./remote.js";
+/** Runs Lighthouse (lab) against already-served URLs. */
+export declare function runLighthouse(root: string, urls: string[], strategies: Strategy[]): Promise<LabReport[]>;