vagejs 0.0.0-stage → 0.2.0

package/dist/core/config.d.ts

@@ -0,0 +1,180 @@
+import { z } from "zod";
+export declare const CONFIG_FILES: string[];
+export declare const configSchema: z.ZodObject<{
+    site: z.ZodOptional<z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lang: z.ZodDefault<z.ZodString>;
+    markdown: z.ZodDefault<z.ZodObject<{
+        html: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            sanitize: "sanitize";
+        }>>;
+        inlineStyles: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    seo: z.ZodDefault<z.ZodObject<{
+        robots: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                userAgent: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+                allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                disallow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            aiTraining: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                disallow: "disallow";
+            }>>;
+            aiSearch: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                disallow: "disallow";
+            }>>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            rules: {
+                userAgent: string | string[];
+                allow: string[];
+                disallow: string[];
+            }[];
+            aiTraining?: "allow" | "disallow" | undefined;
+            aiSearch?: "allow" | "disallow" | undefined;
+        }, boolean | {
+            rules: {
+                userAgent: string | string[];
+                allow: string[];
+                disallow: string[];
+            }[];
+            aiTraining?: "allow" | "disallow" | undefined;
+            aiSearch?: "allow" | "disallow" | undefined;
+        }>>;
+        sitemap: z.ZodDefault<z.ZodBoolean>;
+        llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            full: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            full: boolean;
+        }, boolean | {
+            full: boolean;
+        }>>;
+        structuredData: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            organization: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                url: z.ZodOptional<z.ZodURL>;
+                logo: z.ZodOptional<z.ZodString>;
+                sameAs: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            organization?: {
+                name: string;
+                url?: string | undefined;
+                logo?: string | undefined;
+                sameAs?: string[] | undefined;
+            } | undefined;
+        }, boolean | {
+            organization?: {
+                name: string;
+                url?: string | undefined;
+                logo?: string | undefined;
+                sameAs?: string[] | undefined;
+            } | undefined;
+        }>>;
+    }, z.core.$strict>>;
+    performance: z.ZodDefault<z.ZodObject<{
+        budgets: z.ZodDefault<z.ZodObject<{
+            performance: z.ZodDefault<z.ZodNumber>;
+            accessibility: z.ZodDefault<z.ZodNumber>;
+            seo: z.ZodDefault<z.ZodNumber>;
+            bestPractices: z.ZodDefault<z.ZodNumber>;
+            javascriptKb: z.ZodDefault<z.ZodNumber>;
+            cssKb: z.ZodDefault<z.ZodNumber>;
+            imageKb: z.ZodDefault<z.ZodNumber>;
+            fontKb: z.ZodDefault<z.ZodNumber>;
+            totalKb: z.ZodDefault<z.ZodNumber>;
+            requests: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        lighthouse: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            pages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    deploy: z.ZodDefault<z.ZodObject<{
+        target: z.ZodDefault<z.ZodEnum<{
+            "cloudflare-pages": "cloudflare-pages";
+            "cloudflare-workers": "cloudflare-workers";
+            "github-pages": "github-pages";
+        }>>;
+        cloudflareProject: z.ZodOptional<z.ZodString>;
+        cloudflareWorker: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    security: z.ZodDefault<z.ZodObject<{
+        headers: z.ZodDefault<z.ZodBoolean>;
+        csp: z.ZodDefault<z.ZodEnum<{
+            enforce: "enforce";
+            off: "off";
+            "report-only": "report-only";
+        }>>;
+        cspSources: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            "connect-src": "connect-src";
+            "font-src": "font-src";
+            "frame-src": "frame-src";
+            "img-src": "img-src";
+            "media-src": "media-src";
+            "script-src": "script-src";
+            "style-src": "style-src";
+        }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+        outboundLinks: z.ZodDefault<z.ZodEnum<{
+            lock: "lock";
+            off: "off";
+            require: "require";
+        }>>;
+        spamPatterns: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    guidelines: z.ZodDefault<z.ZodObject<{
+        rulePack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    integrations: z.ZodDefault<z.ZodObject<{
+        ga4: z.ZodOptional<z.ZodObject<{
+            measurementId: z.ZodOptional<z.ZodString>;
+            propertyId: z.ZodOptional<z.ZodString>;
+            consentDefault: z.ZodDefault<z.ZodEnum<{
+                denied: "denied";
+                granted: "granted";
+            }>>;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        gtm: z.ZodOptional<z.ZodObject<{
+            containerId: z.ZodOptional<z.ZodString>;
+            consentDefault: z.ZodDefault<z.ZodEnum<{
+                denied: "denied";
+                granted: "granted";
+            }>>;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        plausible: z.ZodOptional<z.ZodObject<{
+            snippet: z.ZodString;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        clarity: z.ZodOptional<z.ZodObject<{
+            snippet: z.ZodString;
+        }, z.core.$strict>>;
+        indexNow: z.ZodOptional<z.ZodObject<{
+            key: z.ZodString;
+            endpoint: z.ZodDefault<z.ZodURL>;
+        }, z.core.$strict>>;
+        searchConsole: z.ZodOptional<z.ZodObject<{
+            property: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    redirects: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type UserConfig = z.input<typeof configSchema>;
+export type SiteConfig = z.output<typeof configSchema>;
+/** Identity helper that gives config files type checking. */
+export declare function defineConfig(config: UserConfig): UserConfig;
+export declare function findConfigFile(root: string): string | undefined;
+export type ModuleLoader = (file: string) => Promise<Record<string, unknown>>;
+export declare function loadConfig(root: string, load: ModuleLoader): Promise<SiteConfig>;
+/** Validates a raw config object and applies defaults. */
+export declare function parseConfig(raw: unknown, file?: string): SiteConfig;

package/dist/core/config.js

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { VageError } from "./errors.js";
+import { ruleData } from "../guidelines/pack.js";
+export const CONFIG_FILES = ["vage.config.ts", "vage.config.js", "vage.config.mjs"];
+/** `true` -> defaults, `false` -> disabled, object -> options. */
+function toggle(options) {
+    return z
+        .union([z.boolean(), options])
+        .default(true)
+        .transform((v) => (v === true ? options.parse({}) : v === false ? false : v));
+}
+// No whitespace or control characters: these values become robots.txt lines and output paths.
+const token = z.string().min(1).regex(/^[^\s\u0000-\u001f\u007f]+$/, "must not contain spaces or line breaks");
+const userAgents = z.union([token, z.array(token).min(1)]);
+const urlPath = token.regex(/^\//, 'must start with "/"');
+/** Redirect source: a site path without ".." segments (it becomes a file path under dist/). */
+const redirectSource = urlPath.refine((p) => !p.split("/").some((seg) => seg === ".." || seg === "."), 'must not contain "." or ".." segments');
+/** Redirect target: a site path ("/x", not "//host") or an absolute http(s) URL. */
+const redirectTarget = token.regex(/^(\/(?!\/)|https?:\/\/)/, 'must be a site path starting with a single "/" or an http(s) URL');
+const robotsSchema = z.strictObject({
+    rules: z
+        .array(z.strictObject({
+        userAgent: userAgents,
+        allow: z.array(urlPath).default([]),
+        disallow: z.array(urlPath).default([]),
+    }))
+        .default([])
+        .describe("Explicit robots.txt groups, written in order."),
+    aiTraining: z
+        .enum(["allow", "disallow"])
+        .optional()
+        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended). Unset: the * group applies."),
+    aiSearch: z
+        .enum(["allow", "disallow"])
+        .optional()
+        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot). Unset: the * group applies."),
+});
+const seoSchema = z.strictObject({
+    robots: toggle(robotsSchema).describe("Generate robots.txt (true/false or options)."),
+    sitemap: z.boolean().default(true).describe("Generate sitemap.xml (needs `site`)."),
+    llmsTxt: toggle(z.strictObject({
+        full: z.boolean().default(false).describe("Also emit llms-full.txt with the Markdown of every listed page."),
+    })).describe("Generate llms.txt (needs `title`)."),
+    structuredData: toggle(z.strictObject({
+        organization: z
+            .strictObject({
+            name: z.string().min(1),
+            url: z.url().optional(),
+            logo: z.string().min(1).optional(),
+            sameAs: z.array(z.url()).optional(),
+        })
+            .optional()
+            .describe("Organization JSON-LD on the home page. Only true, visible facts."),
+    })).describe("Automatic JSON-LD (WebSite, Organization, Article)."),
+});
+const score = z.number().int().min(0).max(100);
+const kb = z.number().positive();
+const budgetsSchema = z.strictObject({
+    performance: score.default(90).describe("Minimum Lighthouse performance score (lab)."),
+    accessibility: score.default(95).describe("Minimum Lighthouse accessibility score (lab)."),
+    seo: score.default(95).describe("Minimum Lighthouse SEO score (lab)."),
+    bestPractices: score.default(90).describe("Minimum Lighthouse best-practices score (lab)."),
+    javascriptKb: kb.default(100).describe("Max uncompressed JavaScript per page, KB."),
+    cssKb: kb.default(50).describe("Max uncompressed CSS per page, KB."),
+    imageKb: kb.default(500).describe("Max image bytes per page, KB."),
+    fontKb: kb.default(150).describe("Max font bytes per page, KB."),
+    totalKb: kb.default(1000).describe("Max total local bytes per page, KB."),
+    requests: z.number().int().positive().default(30).describe("Max resource requests per page (incl. the HTML)."),
+});
+const performanceSchema = z.strictObject({
+    budgets: budgetsSchema.default(() => budgetsSchema.parse({})).describe("Starting points, not universal standards. Adjust per site."),
+    lighthouse: z
+        .strictObject({
+        enabled: z.boolean().default(false).describe("Run Lighthouse in `vage audit` without --lighthouse. Needs the lighthouse package and Chrome."),
+        pages: z.array(z.string().regex(/^\//)).min(1).default(["/"]).describe("Routes to audit with Lighthouse."),
+    })
+        .default({ enabled: false, pages: ["/"] }),
+});
+// GA4 naming rules and limits: rule pack "ga4.naming".
+const GA4 = ruleData("ga4.naming");
+const ga4Name = z
+    .string()
+    .max(GA4.maxNameLength)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, "must start with a letter and use only letters, numbers and underscores");
+const ga4Param = ga4Name.refine((p) => !GA4.reservedParamPrefixes.some((prefix) => p.startsWith(prefix)), "uses a reserved prefix");
+/** Event map whose keys are validated with GA4 naming rules (record keys alone give unhelpful errors). */
+const ga4Events = z.record(z.string(), z.strictObject({ params: z.array(ga4Param).default([]) })).superRefine((events, ctx) => {
+    for (const name of Object.keys(events)) {
+        const result = ga4Name.safeParse(name);
+        if (!result.success)
+            ctx.addIssue({ code: "custom", path: [name], message: `event name "${name}" ${result.error.issues[0].message}` });
+    }
+});
+const consentDefault = z
+    .enum(["denied", "granted"])
+    .default("denied")
+    .describe("Consent mode default for analytics/ads storage before the visitor chooses. Your site provides the consent UI.");
+/** A tracking snippet pasted from the provider's dashboard; inserted verbatim into <head>. */
+const snippet = z
+    .string()
+    .max(5000)
+    .refine((v) => /<script[\s>]/i.test(v), "must be the <script> snippet from the provider's dashboard")
+    .refine((v) => !/googletagmanager\.com/.test(v), "Google tags belong in integrations.ga4 or integrations.gtm");
+const INDEXNOW = ruleData("indexnow.protocol");
+const integrationsSchema = z
+    .strictObject({
+    ga4: z
+        .strictObject({
+        measurementId: z
+            .string()
+            .regex(/^G-[A-Z0-9]+$/, 'must look like "G-XXXXXXX"')
+            .optional()
+            .describe("GA4 web stream measurement ID (public). Tags are added only when set, e.g. process.env.GA4_MEASUREMENT_ID."),
+        propertyId: z.string().regex(/^\d+$/, "must be the numeric GA4 property ID").optional().describe("Numeric property ID for `vage report analytics`."),
+        consentDefault,
+        events: ga4Events
+            .default({})
+            .describe('Allowed custom events for data-vage-event attributes, e.g. { signup_click: { params: ["plan"] } }.'),
+    })
+        .optional(),
+    gtm: z
+        .strictObject({
+        containerId: z.string().regex(/^GTM-[A-Z0-9]+$/, 'must look like "GTM-XXXXXX"').optional().describe("Google Tag Manager container ID."),
+        consentDefault,
+        events: ga4Events.default({}),
+    })
+        .optional(),
+    plausible: z
+        .strictObject({
+        snippet: snippet.describe("Your site's script snippet from Plausible (Site settings → Site installation)."),
+        events: z
+            .record(z.string().min(1).max(120), z.strictObject({ params: z.array(z.string().min(1)).default([]) }))
+            .default({})
+            .describe("Custom events for data-vage-event, sent with plausible(name, { props })."),
+    })
+        .optional(),
+    clarity: z
+        .strictObject({
+        snippet: snippet.describe("Tracking code from Clarity (Settings → Setup → Install manually)."),
+    })
+        .optional()
+        .describe("Microsoft Clarity. window.vageConsent.update() also sends Clarity's consentv2 signal."),
+    indexNow: z
+        .strictObject({
+        key: z.string().regex(new RegExp(INDEXNOW.keyPattern), "must be 8-128 characters: letters, digits or dashes").describe("Public IndexNow key; served as /<key>.txt."),
+        endpoint: z.url().default(INDEXNOW.endpoint).describe("IndexNow endpoint (default: the shared api.indexnow.org)."),
+    })
+        .optional(),
+    searchConsole: z
+        .strictObject({
+        property: z
+            .string()
+            .regex(/^(sc-domain:[^/\s]+|https?:\/\/\S+\/)$/, 'must be "sc-domain:example.com" or a URL prefix ending in "/"')
+            .optional()
+            .describe("Search Console property for `vage report search`."),
+    })
+        .optional(),
+})
+    .refine((i) => !(i.ga4?.measurementId && i.gtm?.containerId), {
+    message: "Configure GA4 directly (ga4.measurementId) or through Tag Manager (gtm.containerId), not both: loading both double-counts.",
+});
+export const configSchema = z.strictObject({
+    site: z
+        .url({ protocol: /^https?$/ })
+        .refine((s) => new URL(s).pathname === "/", "must be an origin without a path (base paths are not supported yet)")
+        .transform((s) => new URL(s).origin)
+        .optional()
+        .describe("Production origin, e.g. https://example.com. Needed for canonical URLs and sitemap.xml."),
+    title: z.string().min(1).optional().describe("Site name: page titles, og:site_name, llms.txt heading."),
+    description: z.string().min(1).optional().describe("Fallback meta description; llms.txt summary."),
+    lang: z.string().min(1).default("en").describe("<html lang> value."),
+    markdown: z
+        .strictObject({
+        html: z
+            .enum(["sanitize", "allow"])
+            .default("sanitize")
+            .describe('"sanitize" removes scripts, event handlers, javascript: URLs, iframes and forms from page content. "allow" trusts all content authors.'),
+        inlineStyles: z
+            .boolean()
+            .default(false)
+            .describe('Keep style="..." attributes in page content (sanitize mode). Off by default: inline styles are the usual way to hide spam links. Put styling in layouts.'),
+    })
+        .default({ html: "sanitize", inlineStyles: false }),
+    seo: seoSchema.default(() => seoSchema.parse({})),
+    performance: performanceSchema.default(() => performanceSchema.parse({})),
+    deploy: z
+        .strictObject({
+        target: z
+            .enum(["github-pages", "cloudflare-pages", "cloudflare-workers"])
+            .default("github-pages")
+            .describe("Host used by `vage deploy`. Cloudflare now creates new sites as Workers: prefer cloudflare-workers there."),
+        cloudflareProject: z.string().regex(/^[a-z0-9][a-z0-9-]{0,57}$/).optional().describe("Cloudflare Pages project name."),
+        cloudflareWorker: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
+            .optional()
+            .describe("Cloudflare Worker name (cloudflare-workers target, when the project has no wrangler config). Defaults to cloudflareProject."),
+    })
+        .default({ target: "github-pages" }),
+    security: z
+        .strictObject({
+        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare targets)."),
+        csp: z
+            .enum(["enforce", "report-only", "off"])
+            .default("enforce")
+            .describe("Content Security Policy generated from the built pages: hashes of inline scripts/styles plus the origins your layouts and analytics load."),
+        cspSources: z
+            .partialRecord(z.enum(["script-src", "style-src", "img-src", "font-src", "connect-src", "frame-src", "media-src"]), z.array(z.string().regex(/^('[a-z0-9-]+'|https?:\/\/[^\s;,']+|[a-z]+:)$/, "must be a source like https://cdn.example.com or 'self'")))
+            .default({})
+            .describe("Extra sources per directive, e.g. { \"connect-src\": [\"https://api.example.com\"] }."),
+        outboundLinks: z
+            .enum(["require", "lock", "off"])
+            .default("lock")
+            .describe('"lock": when links.lock.json exists, every external domain the site links to must be listed there (approve with `vage links approve`); new domains fail `vage check`. Catches injected spam links. "require": the same, and a missing links.lock.json is an error, so deleting it can\'t switch the guard off. "off": no guard.'),
+        spamPatterns: z.boolean().default(true).describe("Warn in `vage check` about common spam words (casino, pills, payday loans...) in page text and links."),
+    })
+        .default({ headers: true, csp: "enforce", cspSources: {}, outboundLinks: "lock", spamPatterns: true }),
+    guidelines: z
+        .strictObject({
+        rulePack: z
+            .string()
+            .regex(/^\d{4}\.\d{1,2}\.\d+$/)
+            .optional()
+            .describe("Pin the rule-pack version. Builds fail when the installed vagejs ships a different pack, until you review its changelog and update the pin."),
+    })
+        .default({}),
+    integrations: integrationsSchema.default({}).describe("Optional analytics and search integrations. All off unless configured."),
+    redirects: z
+        .record(z.string(), redirectTarget)
+        .superRefine((redirects, ctx) => {
+        for (const from of Object.keys(redirects)) {
+            const result = redirectSource.safeParse(from);
+            if (!result.success)
+                ctx.addIssue({ code: "custom", path: [from], message: `redirect source "${from}" ${result.error.issues[0].message}` });
+        }
+    })
+        .default({})
+        .describe("Old path -> new path or URL. Built as noindex meta-refresh pages; dev answers 301."),
+});
+/** Identity helper that gives config files type checking. */
+export function defineConfig(config) {
+    return config;
+}
+export function findConfigFile(root) {
+    return CONFIG_FILES.map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
+}
+export async function loadConfig(root, load) {
+    const file = findConfigFile(root);
+    return parseConfig(file ? (await load(file)).default : {}, file);
+}
+/** Validates a raw config object and applies defaults. */
+export function parseConfig(raw, file) {
+    const result = configSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        throw new VageError(`Invalid config:\n${z.prettifyError(result.error)}`, file);
+    }
+    return result.data;
+}

package/dist/core/errors.d.ts

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

package/dist/core/errors.js

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

package/dist/core/html.d.ts

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

package/dist/core/html.js

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

package/dist/core/loader.d.ts

@@ -0,0 +1,10 @@
+import { type InlineConfig, type ViteDevServer } from "vite";
+import type { ModuleLoader } from "./config.js";
+/** Shared Vite options. configFile: false keeps a project's own vite.config out of the picture. */
+export declare function baseViteConfig(root: string): InlineConfig;
+export declare function viteLoader(server: ViteDevServer): ModuleLoader;
+/** A headless Vite server used only to import TypeScript config and layout files during a build. */
+export declare function createBuildLoader(root: string): Promise<{
+    load: ModuleLoader;
+    close: () => Promise<void>;
+}>;

package/dist/core/loader.js

@@ -0,0 +1,16 @@
+import { createServer } from "vite";
+/** Shared Vite options. configFile: false keeps a project's own vite.config out of the picture. */
+export function baseViteConfig(root) {
+    return { root, configFile: false, logLevel: "warn", appType: "custom" };
+}
+export function viteLoader(server) {
+    return (file) => server.ssrLoadModule(file);
+}
+/** A headless Vite server used only to import TypeScript config and layout files during a build. */
+export async function createBuildLoader(root) {
+    const server = await createServer({
+        ...baseViteConfig(root),
+        server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+    });
+    return { load: viteLoader(server), close: () => server.close() };
+}

package/dist/core/pages.d.ts

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