vagejs 0.0.0-stage → 0.1.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,80 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/brand/vagejs-logo.svg" alt="VAGE JS" width="320">
+</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.
+# VAGE JS
+
+An AI-native, static-first web framework. **Pre-release (0.x).**
+
+## What works today
+
+```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] [--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-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
+```
+
+Generated sites include `AGENTS.md` (conventions, recipes, definition of done) and `CLAUDE.md` (imports AGENTS.md).
+
+Failures exit with code 1. With `--json`, output is `{ "ok": true, ... }` or `{ "ok": false, "error": "..." }`.
+
+See [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md) for routing, frontmatter, layouts and config, and [`docs/DECISIONS.md`](docs/DECISIONS.md) for design decisions.
+
+## Getting started
+
+```bash
+npm create vagejs@latest my-site
+cd my-site
+npm install
+npm run dev
+```
+
+## Releasing
+
+See [docs/RELEASING.md](docs/RELEASING.md).
+
+## Development
+
+```bash
+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)
+```
+
+## Planned, not implemented
+
+Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server. See `VAGE_JS_BUILD_SPEC.md`.
+
+## 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).
+
+## Brand assets
+
+- `assets/brand/vagejs-icon.svg`: the icon, as received (with C2PA content credentials).
+- `assets/brand/vagejs-logo.svg`: the wordmark 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.
+- 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[]>;

package/dist/audit/lighthouse.js

@@ -0,0 +1,48 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { VageError } from "../core/errors.js";
+import { labReport } from "./remote.js";
+/**
+ * Loads Lighthouse from the user's project. It is an optional peer dependency
+ * (large, and needs Chrome), so it is never required for build or check.
+ */
+async function loadLighthouse(root) {
+    const require = createRequire(pathToFileURL(`${root}/package.json`));
+    let entry;
+    try {
+        entry = require.resolve("lighthouse");
+    }
+    catch {
+        throw new VageError('Lighthouse is not installed. Run "npm install --save-dev lighthouse" (requires Chrome), or audit without --lighthouse.');
+    }
+    const mod = await import(pathToFileURL(entry).href);
+    // chrome-launcher is a Lighthouse dependency; resolve it from there.
+    const launcher = await import(pathToFileURL(createRequire(entry).resolve("chrome-launcher")).href);
+    return { lighthouse: mod.default, desktopConfig: mod.desktopConfig, launcher };
+}
+/** Runs Lighthouse (lab) against already-served URLs. */
+export async function runLighthouse(root, urls, strategies) {
+    const { lighthouse, desktopConfig, launcher } = await loadLighthouse(root);
+    let chrome;
+    try {
+        chrome = await launcher.launch({ chromeFlags: ["--headless=new"] });
+    }
+    catch (err) {
+        throw new VageError(`Could not start Chrome for Lighthouse: ${err.message}. Install Chrome or set CHROME_PATH.`);
+    }
+    try {
+        const reports = [];
+        for (const url of urls) {
+            for (const strategy of strategies) {
+                const result = await lighthouse(url, { port: chrome.port, output: "json", logLevel: "error", onlyCategories: ["performance", "accessibility", "seo", "best-practices"] }, strategy === "desktop" ? desktopConfig : undefined);
+                if (!result)
+                    throw new VageError(`Lighthouse returned no result for ${url}.`);
+                reports.push(labReport(result.lhr, "lighthouse", url, strategy));
+            }
+        }
+        return reports;
+    }
+    finally {
+        chrome.kill();
+    }
+}

package/dist/audit/remote.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { redact, type HttpOptions } from "../integrations/http.js";
+import { type Rating, type VitalName } from "./vitals.js";
+export type Strategy = "mobile" | "desktop";
+export type RemoteOptions = HttpOptions;
+export { redact };
+declare const CATEGORY_IDS: readonly ["performance", "accessibility", "seo", "best-practices"];
+declare const psiSchema: z.ZodObject<{
+    lighthouseResult: z.ZodObject<{
+        lighthouseVersion: z.ZodString;
+        fetchTime: z.ZodString;
+        finalDisplayedUrl: z.ZodOptional<z.ZodString>;
+        categories: z.ZodRecord<z.ZodString, z.ZodObject<{
+            score: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        audits: z.ZodRecord<z.ZodString, z.ZodObject<{
+            title: z.ZodString;
+            score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            numericValue: z.ZodOptional<z.ZodNumber>;
+            displayValue: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export interface LabReport {
+    source: "pagespeed-insights" | "lighthouse";
+    url: string;
+    strategy: Strategy;
+    fetchTime: string;
+    toolVersion: string;
+    /** 0-100, or null when the tool returned no score. */
+    scores: Record<(typeof CATEGORY_IDS)[number], number | null>;
+    metrics: {
+        lcpMs?: number;
+        cls?: number;
+        tbtMs?: number;
+        fcpMs?: number;
+        speedIndexMs?: number;
+    };
+    /** Lowest-scoring audits, most impactful first. */
+    opportunities: {
+        id: string;
+        title: string;
+        displayValue?: string;
+    }[];
+}
+/** Normalizes a Lighthouse result (from PSI or a local run). */
+export declare function labReport(lhr: z.infer<typeof psiSchema>["lighthouseResult"], source: LabReport["source"], url: string, strategy: Strategy): LabReport;
+export declare function pageSpeed(url: string, strategy: Strategy, key: string | undefined, opts?: RemoteOptions): Promise<LabReport>;
+export interface FieldReport {
+    source: "crux";
+    /** "url" when page-level data exists, otherwise "origin". */
+    scope: "url" | "origin";
+    formFactor: "PHONE" | "DESKTOP";
+    collectionPeriod?: string;
+    metrics: Partial<Record<VitalName, {
+        p75: number;
+        rating: Rating;
+    }>>;
+}
+/**
+ * Queries the CrUX API for the page, falling back to the origin. Returns
+ * undefined when neither has data. A 404 is treated as "no data"; the API
+ * docs do not specify this response, so it is an observed-behavior assumption.
+ */
+export declare function cruxField(url: string, strategy: Strategy, key: string, opts?: RemoteOptions): Promise<FieldReport | undefined>;