simple-site-generator 0.1.3 → 0.2.0

package/dist/types/verify/class-coverage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Markup ↔ stylesheet coverage.
+ *
+ * The kit's design system is UnoCSS configuration: `ssg-*` classes in markup
+ * resolve to shortcuts and preflights that are generated at build time. Nothing
+ * connects the two, and every failure in that gap is **silent** — which is the
+ * class of defect this repository keeps meeting (see `docs/adr/0001` and
+ * `docs/adr/0004`).
+ *
+ * The concrete case that motivated this: a shortcut array in `design.ts` lost
+ * its separating comma, which parses as a computed member access. The entry
+ * *after* the comma survived, the entry before it vanished, and
+ * `tsc`, `oxlint` and the whole test suite stayed green while the class it named
+ * rendered unstyled. It happened twice in one afternoon — `ssg-business__band-demo`
+ * and then `ssg-proof-section__heading` — and was caught both times only by
+ * looking at the page.
+ *
+ * This is the check that would have caught it mechanically. It compares what the
+ * built HTML *asks for* against what the built CSS *provides*, which is a set
+ * difference over two files the build has already written.
+ */
+/**
+ * `ssg-*` classes that carry no styling by design.
+ *
+ * These are hooks: targets for tests and for `data-ssg`-style selection, or
+ * structural markers a component uses to find its own nodes. They must be listed
+ * rather than merely tolerated, because "this class has no rule" should be a
+ * decision someone made, not an accident — which is the whole point of the check.
+ *
+ * Only `ssg-*` classes are checked at all. Third-party classes are out of scope
+ * on purpose: Quasar adds state classes at runtime (`q-btn--active`, `body--dark`)
+ * that are legitimately absent from the prerendered sheet.
+ */
+export declare const UNSTYLED_HOOKS: readonly string[];
+/** Class tokens a document asks for. */
+export declare function collectMarkupClasses(html: string): Set<string>;
+/**
+ * Class names a stylesheet mentions.
+ *
+ * The whole sheet is scanned rather than just its selector text. An earlier
+ * version stripped declaration blocks first to be precise about it, and was
+ * wrong: stripping innermost blocks turns `@media(...){.a{color:red}}` into
+ * `@media(...){.a}`, and the next pass then strips `{.a}` — deleting the very
+ * selector it was looking for. It reported a styled class as unstyled, which is
+ * the one direction that would get a check like this switched off.
+ *
+ * Scanning everything is safe here because the check only asks about `ssg-*`
+ * names, and generated CSS contains those in selectors and nowhere else. A
+ * declaration value cannot produce one, and UnoCSS emits no comments.
+ */
+export declare function collectCssClasses(css: string): Set<string>;
+export interface ClassCoverageIssue {
+    page: string;
+    className: string;
+}
+/**
+ * `ssg-*` classes that a page asks for and the stylesheet does not provide.
+ *
+ * Reported per page rather than as a flat list: which page uses an unstyled class
+ * is the first thing needed to find it.
+ */
+export declare function checkClassCoverage(pages: {
+    page: string;
+    html: string;
+}[], css: string, hooks?: readonly string[]): ClassCoverageIssue[];

package/dist/types/verify/ignore.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True when a built page (its path relative to the output root) matches one of
+ * the `--ignore` globs.
+ *
+ * Kept in its own module — rather than inline in `verify.ts` — so it can be
+ * unit-tested without importing the Lighthouse half of the verifier.
+ */
+export declare function isIgnored(page: string, patterns: readonly string[]): boolean;

package/dist/types/verify/lighthouse.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceEntry } from './budgets.js';
+/**
+ * Run Lighthouse against a URL and return the parts `ssg verify` acts on.
+ *
+ * Lighthouse is used as a **library** rather than the CLI so the verification
+ * runs in-process, reports its own scores, and does not require the caller to
+ * have the `lighthouse` binary on `PATH`.
+ */
+export interface LighthouseVerification {
+    scores: Record<string, number>;
+    resources: ResourceEntry[];
+    /**
+     * Failing audit ids per category. `verify` reports these next to a score so a
+     * failed accessibility/SEO score names the audit that failed instead of only
+     * the number — a bare "seo score is 82" is not actionable.
+     */
+    failures: Record<string, string[]>;
+    /** Failing-audit id to the selectors of the nodes that failed it. */
+    details: Record<string, string[]>;
+}
+export interface LighthouseOptions {
+    /** Chromium/Chrome binary. Falls back to `CHROME_PATH`, then auto-detection. */
+    chromePath?: string;
+    /** `mobile` (default) or `desktop` — the two form factors `verify` reports. */
+    formFactor?: 'mobile' | 'desktop';
+}
+export declare function runLighthouse(url: string, options?: LighthouseOptions): Promise<LighthouseVerification>;

package/dist/types/verify/seo-surface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Verify the SEO surface of built HTML.
+ *
+ * These are the checks that would have caught the original template's SEO
+ * defect: it did produce meta tags in some configurations, but never asserted
+ * anything about them, so a page could ship with no description, two titles, or
+ * unparseable structured data and nothing noticed. Each check is a property a
+ * crawler depends on.
+ */
+export interface SeoSurfaceIssue {
+    /** Output file the problem was found in, e.g. `index.html`. */
+    page: string;
+    message: string;
+}
+export interface SeoSurfaceOptions {
+    /** Site origin, used to assert the canonical is absolute. */
+    siteUrl?: string;
+}
+/**
+ * Check one built page. Returns every problem found, so a broken build reports
+ * all of its SEO faults at once rather than one per run.
+ */
+export declare function checkSeoSurface(html: string, page: string, options?: SeoSurfaceOptions): SeoSurfaceIssue[];

package/dist/types/verify/serve.d.ts

@@ -0,0 +1,6 @@
+export interface StaticServer {
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startStaticServer(root: string): Promise<StaticServer>;

package/dist/verify/budgets.js

@@ -0,0 +1,180 @@
+/**
+ * Transfer-size budgets.
+ *
+ * The tiered policy from the plan: byte budgets are **hard** failures because
+ * they are deterministic and directly measurable, while Lighthouse performance
+ * is a **warn** because it varies with machine and network simulation. A gate
+ * that fails randomly gets disabled, so only the deterministic half blocks.
+ */
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+import { gzipSync } from 'node:zlib';
+export const DEFAULT_BUDGETS = {
+    jsBytes: 250 * 1024,
+    cssBytes: 60 * 1024
+};
+function kindOf(resourceType) {
+    if (resourceType === 'script')
+        return 'js';
+    if (resourceType === 'stylesheet')
+        return 'css';
+    return 'other';
+}
+export function formatBytes(bytes) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+}
+/**
+ * Evaluate transferred bytes against the budgets.
+ *
+ * `transferSize` (compressed, over the wire) is used rather than decoded size,
+ * because that is what the visitor actually pays for.
+ */
+export function evaluateBudgets(resources, budgets = DEFAULT_BUDGETS) {
+    let js = 0;
+    let css = 0;
+    for (const resource of resources) {
+        const size = resource.transferSize ?? 0;
+        if (kindOf(resource.resourceType) === 'js')
+            js += size;
+        else if (kindOf(resource.resourceType) === 'css')
+            css += size;
+    }
+    const issues = [];
+    if (js > budgets.jsBytes) {
+        issues.push(`JavaScript budget exceeded: ${formatBytes(js)} transferred, budget is ${formatBytes(budgets.jsBytes)}`);
+    }
+    if (css > budgets.cssBytes) {
+        issues.push(`CSS budget exceeded: ${formatBytes(css)} transferred, budget is ${formatBytes(budgets.cssBytes)}`);
+    }
+    return { ok: issues.length === 0, totals: { js, css }, issues };
+}
+/** Scores below these are a warning, not a failure (see the tiering note above). */
+/**
+ * Warn when a measured total is within this fraction of its ceiling.
+ *
+ * A budget a site is always near is a cliff: everything passes until the day a
+ * dependency bump pushes it over, and then the failure looks sudden. A warning at
+ * 10% remaining turns "no headroom" into something visible on every run.
+ *
+ * Deliberately not a failure. Being inside the budget is not a defect, and the
+ * deterministic tier is reserved for things that are.
+ */
+export const HEADROOM_WARNING_FRACTION = 0.1;
+export function budgetHeadroomWarnings(totals, budgets = DEFAULT_BUDGETS, fraction = HEADROOM_WARNING_FRACTION) {
+    const warnings = [];
+    const check = (label, actual, limit) => {
+        // A zero total is a failed measurement, which `evaluateTotals` already
+        // reports as a failure; warning about its headroom would be noise on top.
+        if (actual <= 0 || limit <= 0)
+            return;
+        const remaining = (limit - actual) / limit;
+        if (remaining >= 0 && remaining <= fraction) {
+            warnings.push(`${label} is within ${Math.round(fraction * 100)}% of its budget: ${formatBytes(actual)} of ${formatBytes(limit)}, ${formatBytes(limit - actual)} left`);
+        }
+    };
+    check('JavaScript', totals.js, budgets.jsBytes);
+    check('CSS', totals.css, budgets.cssBytes);
+    return warnings;
+}
+export const DEFAULT_SCORE_TARGETS = {
+    /** Must equal `required` exactly — anything lower is a defect, not a trade-off. */
+    required: { accessibility: 100, 'best-practices': 100, seo: 100 },
+    /** A warning threshold: performance varies with the measuring machine. */
+    warnBelow: { performance: 90 }
+};
+export function evaluateScores(scores, targets = DEFAULT_SCORE_TARGETS) {
+    const issues = [];
+    const warnings = [];
+    for (const [category, minimum] of Object.entries(targets.required)) {
+        const actual = scores[category];
+        if (actual === undefined)
+            continue;
+        if (actual < minimum) {
+            issues.push(`${category} score is ${actual}, expected ${minimum}`);
+        }
+    }
+    for (const [category, minimum] of Object.entries(targets.warnBelow)) {
+        const actual = scores[category];
+        if (actual === undefined)
+            continue;
+        if (actual < minimum) {
+            warnings.push(`${category} score is ${actual}, below the ${minimum} target`);
+        }
+    }
+    return { ok: issues.length === 0, issues, warnings };
+}
+/**
+ * Measure the transferred JavaScript and CSS of a built site **from disk**.
+ *
+ * This is deliberately not read from Lighthouse. Its `resource-summary` audit
+ * reports `transferSize: 0` when the trace captures no network activity
+ * (reproduced in a sandboxed Chromium), and a budget that measures nothing
+ * silently reports "OK" — a gate that cannot fail is worse than no gate.
+ * Reading the built files is deterministic, needs no browser, and lets the byte
+ * half of `ssg verify` run with `--no-lighthouse`.
+ *
+ * Sizes are gzipped, because that is what actually crosses the network.
+ */
+export async function measureBuildAssets(root) {
+    const files = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            const type = /\.(mjs|js)$/.test(entry.name)
+                ? 'js'
+                : entry.name.endsWith('.css')
+                    ? 'css'
+                    : null;
+            if (!type)
+                continue;
+            const compressed = gzipSync(await fs.readFile(full)).length;
+            files.push({ file: relative(root, full), bytes: compressed, type });
+        }
+    }
+    await walk(root);
+    return {
+        js: files
+            .filter((f) => f.type === 'js')
+            .reduce((total, f) => total + f.bytes, 0),
+        css: files
+            .filter((f) => f.type === 'css')
+            .reduce((total, f) => total + f.bytes, 0),
+        files: files.sort((a, b) => b.bytes - a.bytes)
+    };
+}
+/**
+ * Evaluate measured byte totals against the budgets.
+ *
+ * An all-zero measurement is **no measurement**, not a pass: a built site always
+ * ships some JavaScript, so zero means the measurement failed.
+ */
+export function evaluateTotals(totals, budgets = DEFAULT_BUDGETS) {
+    if (totals.js + totals.css === 0) {
+        return {
+            ok: false,
+            totals,
+            issues: [
+                'Byte measurement returned 0 bytes for both JavaScript and CSS — the budget gate cannot be trusted. Does the build output exist?'
+            ]
+        };
+    }
+    const issues = [];
+    if (totals.js > budgets.jsBytes) {
+        issues.push(`JavaScript budget exceeded: ${formatBytes(totals.js)} transferred, budget is ${formatBytes(budgets.jsBytes)}`);
+    }
+    if (totals.css > budgets.cssBytes) {
+        issues.push(`CSS budget exceeded: ${formatBytes(totals.css)} transferred, budget is ${formatBytes(budgets.cssBytes)}`);
+    }
+    return { ok: issues.length === 0, totals, issues };
+}

package/dist/verify/class-coverage.js

@@ -0,0 +1,114 @@
+/**
+ * Markup ↔ stylesheet coverage.
+ *
+ * The kit's design system is UnoCSS configuration: `ssg-*` classes in markup
+ * resolve to shortcuts and preflights that are generated at build time. Nothing
+ * connects the two, and every failure in that gap is **silent** — which is the
+ * class of defect this repository keeps meeting (see `docs/adr/0001` and
+ * `docs/adr/0004`).
+ *
+ * The concrete case that motivated this: a shortcut array in `design.ts` lost
+ * its separating comma, which parses as a computed member access. The entry
+ * *after* the comma survived, the entry before it vanished, and
+ * `tsc`, `oxlint` and the whole test suite stayed green while the class it named
+ * rendered unstyled. It happened twice in one afternoon — `ssg-business__band-demo`
+ * and then `ssg-proof-section__heading` — and was caught both times only by
+ * looking at the page.
+ *
+ * This is the check that would have caught it mechanically. It compares what the
+ * built HTML *asks for* against what the built CSS *provides*, which is a set
+ * difference over two files the build has already written.
+ */
+/**
+ * `ssg-*` classes that carry no styling by design.
+ *
+ * These are hooks: targets for tests and for `data-ssg`-style selection, or
+ * structural markers a component uses to find its own nodes. They must be listed
+ * rather than merely tolerated, because "this class has no rule" should be a
+ * decision someone made, not an accident — which is the whole point of the check.
+ *
+ * Only `ssg-*` classes are checked at all. Third-party classes are out of scope
+ * on purpose: Quasar adds state classes at runtime (`q-btn--active`, `body--dark`)
+ * that are legitimately absent from the prerendered sheet.
+ */
+export const UNSTYLED_HOOKS = [
+    'ssg-breadcrumbs__sep',
+    'ssg-content',
+    'ssg-content__carousel',
+    'ssg-content__markdown',
+    'ssg-cta',
+    // The demo's grid and per-stop group carry SVG presentation attributes (`fill`,
+    // `mask`) rather than CSS, and the group is only a wrapper: its children are
+    // what is styled. Both are selection hooks for the component's own tests.
+    'ssg-demo__grid',
+    'ssg-demo__stop',
+    'ssg-header__language',
+    'ssg-header__menu-toggle',
+    'ssg-landing',
+    'ssg-primary-navigation',
+    'ssg-proof-section__facts',
+    'ssg-proof-section__reviews',
+    'ssg-proof__text'
+];
+/** Class tokens a document asks for. */
+export function collectMarkupClasses(html) {
+    // Comments and scripts first. The SEO surface check learned this the hard way:
+    // it counted tags inside an HTML comment, so a page whose head was entirely
+    // commented out passed. The same trap applies here, and a JSON-LD block is a
+    // script whose content is not markup either.
+    const markup = html
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<script\b[\s\S]*?<\/script>/gi, '');
+    const classes = new Set();
+    for (const match of markup.matchAll(/\bclass\s*=\s*"([^"]*)"/gi)) {
+        for (const token of match[1].split(/\s+/)) {
+            if (token)
+                classes.add(token);
+        }
+    }
+    return classes;
+}
+/**
+ * Class names a stylesheet mentions.
+ *
+ * The whole sheet is scanned rather than just its selector text. An earlier
+ * version stripped declaration blocks first to be precise about it, and was
+ * wrong: stripping innermost blocks turns `@media(...){.a{color:red}}` into
+ * `@media(...){.a}`, and the next pass then strips `{.a}` — deleting the very
+ * selector it was looking for. It reported a styled class as unstyled, which is
+ * the one direction that would get a check like this switched off.
+ *
+ * Scanning everything is safe here because the check only asks about `ssg-*`
+ * names, and generated CSS contains those in selectors and nowhere else. A
+ * declaration value cannot produce one, and UnoCSS emits no comments.
+ */
+export function collectCssClasses(css) {
+    const classes = new Set();
+    for (const match of css.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)) {
+        classes.add(match[1]);
+    }
+    return classes;
+}
+/**
+ * `ssg-*` classes that a page asks for and the stylesheet does not provide.
+ *
+ * Reported per page rather than as a flat list: which page uses an unstyled class
+ * is the first thing needed to find it.
+ */
+export function checkClassCoverage(pages, css, hooks = UNSTYLED_HOOKS) {
+    const provided = collectCssClasses(css);
+    const exempt = new Set(hooks);
+    const issues = [];
+    for (const { page, html } of pages) {
+        for (const className of collectMarkupClasses(html)) {
+            if (!className.startsWith('ssg-'))
+                continue;
+            if (exempt.has(className))
+                continue;
+            if (provided.has(className))
+                continue;
+            issues.push({ page, className });
+        }
+    }
+    return issues;
+}

package/dist/verify/ignore.js

@@ -0,0 +1,11 @@
+import { matchesGlob } from 'node:path';
+/**
+ * True when a built page (its path relative to the output root) matches one of
+ * the `--ignore` globs.
+ *
+ * Kept in its own module — rather than inline in `verify.ts` — so it can be
+ * unit-tested without importing the Lighthouse half of the verifier.
+ */
+export function isIgnored(page, patterns) {
+    return patterns.some((pattern) => matchesGlob(page, pattern));
+}

package/dist/verify/lighthouse.js

@@ -0,0 +1,98 @@
+import { launch } from 'chrome-launcher';
+import lighthouse from 'lighthouse';
+/**
+ * Categories that must be measured. Performance is included because the plan
+ * warns on it; `verify` decides what is fatal.
+ */
+const CATEGORIES = ['performance', 'accessibility', 'best-practices', 'seo'];
+export async function runLighthouse(url, options = {}) {
+    const chromePath = options.chromePath ?? process.env.CHROME_PATH;
+    if (!chromePath) {
+        throw new Error('No Chromium binary found. Set CHROME_PATH to a Chrome/Chromium executable (for example CHROME_PATH=/usr/bin/chromium ssg verify).');
+    }
+    const chrome = await launch({
+        chromePath,
+        chromeFlags: ['--headless', '--no-sandbox', '--disable-gpu']
+    });
+    try {
+        const result = await lighthouse(url, {
+            port: chrome.port,
+            output: 'json',
+            logLevel: 'error',
+            onlyCategories: CATEGORIES
+        }, 
+        // Lighthouse 12+ expects the form factor in the config's settings.
+        options.formFactor === 'desktop'
+            ? {
+                extends: 'lighthouse:default',
+                settings: {
+                    formFactor: 'desktop',
+                    screenEmulation: {
+                        mobile: false,
+                        width: 1350,
+                        height: 940,
+                        deviceScaleFactor: 1,
+                        disabled: false
+                    }
+                }
+            }
+            : { extends: 'lighthouse:default' });
+        if (!result) {
+            throw new Error('Lighthouse returned no result');
+        }
+        const { lhr } = result;
+        const scores = {};
+        const failures = {};
+        for (const [key, category] of Object.entries(lhr.categories)) {
+            const refs = category.auditRefs ?? [];
+            const failing = refs
+                .map((ref) => lhr.audits[ref.id])
+                .filter((audit) => audit &&
+                audit.score !== null &&
+                audit.score !== undefined &&
+                audit.score < 1)
+                .map((audit) => audit.id);
+            if (failing.length)
+                failures[key] = failing;
+            if (category.score === null || category.score === undefined)
+                continue;
+            // Lighthouse reports 0–1; a 0–100 integer is what people compare against.
+            scores[key] = Math.round(category.score * 100);
+        }
+        // The selector of the nodes behind each failing audit, so a failed
+        // accessibility or SEO score points at an element instead of only an id.
+        const details = {};
+        for (const audit of Object.values(lhr.audits)) {
+            if (!audit ||
+                audit.score === null ||
+                audit.score === undefined ||
+                audit.score >= 1) {
+                continue;
+            }
+            const items = audit.details?.items;
+            const selectors = (Array.isArray(items) ? items : [])
+                .map((item) => item.node?.selector)
+                .filter((selector) => Boolean(selector))
+                .slice(0, 3);
+            if (selectors.length)
+                details[audit.id] = selectors;
+        }
+        // Measured from `resource-summary`, which reports one row per resource TYPE
+        // with a total `transferSize`. `network-requests` is not used: it only lists
+        // requests Lighthouse observed in its own trace, so a warm cache makes it
+        // under-report and the budget gate would pass vacuously.
+        const summaryAudit = lhr.audits['resource-summary'];
+        const resources = (summaryAudit?.details?.items ?? [])
+            .filter((item) => typeof item === 'object' &&
+            item !== null &&
+            typeof item.resourceType === 'string')
+            .map((item) => ({
+            resourceType: item.resourceType,
+            transferSize: Number(item.transferSize) || 0
+        }));
+        return { scores, resources, failures, details };
+    }
+    finally {
+        await chrome.kill();
+    }
+}

package/dist/verify/seo-surface.js

@@ -0,0 +1,97 @@
+/**
+ * Verify the SEO surface of built HTML.
+ *
+ * These are the checks that would have caught the original template's SEO
+ * defect: it did produce meta tags in some configurations, but never asserted
+ * anything about them, so a page could ship with no description, two titles, or
+ * unparseable structured data and nothing noticed. Each check is a property a
+ * crawler depends on.
+ */
+function countMatches(html, pattern) {
+    return [...html.matchAll(pattern)].length;
+}
+/**
+ * Check one built page. Returns every problem found, so a broken build reports
+ * all of its SEO faults at once rather than one per run.
+ */
+export function checkSeoSurface(html, page, options = {}) {
+    const issues = [];
+    const add = (message) => issues.push({ page, message });
+    // Comments are meta-text, not page content. The app template's own comments
+    // mention `<h1>`, and counting those made a page that renders exactly one
+    // heading report "3 <h1> tags". Every check below therefore runs on the
+    // comment-free document.
+    html = html.replace(/<!--[\s\S]*?-->/g, '');
+    // A page the site has deliberately marked `noindex` (the 404, for example) is
+    // excluded from the index, so the tags that exist to describe an indexed page
+    // — canonical, description, structured data — are not required of it. A title,
+    // an h1 and a language still are: the page is rendered and read either way.
+    const noindex = /<meta\b[^>]*\bname=["']?robots["']?[^>]*\bcontent=["'][^"']*noindex/i.test(html);
+    // Exactly one <title>: two of them means a crawler picks one arbitrarily.
+    const titleCount = countMatches(html, /<title\b[^>]*>[\s\S]*?<\/title>/gi);
+    if (titleCount === 0)
+        add('no <title>');
+    if (titleCount > 1)
+        add(`${titleCount} <title> tags — expected exactly one`);
+    const title = html.match(/<title\b[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim();
+    if (titleCount === 1 && !title)
+        add('<title> is empty');
+    // Exactly one canonical, and it must be absolute.
+    const canonical = [
+        ...html.matchAll(/<link\b[^>]*\brel=["']?canonical["']?[^>]*>/gi)
+    ];
+    if (!noindex && canonical.length === 0)
+        add('no canonical link');
+    if (canonical.length > 1) {
+        add(`${canonical.length} canonical links — expected exactly one`);
+    }
+    const canonicalHref = canonical[0]?.[0].match(/\bhref=["']([^"']+)["']/i)?.[1];
+    if (canonical.length === 1 && !canonicalHref) {
+        add('canonical link has no href');
+    }
+    else if (canonicalHref && !/^https?:\/\//i.test(canonicalHref)) {
+        add(`canonical "${canonicalHref}" is not absolute`);
+    }
+    else if (canonicalHref && options.siteUrl) {
+        const origin = options.siteUrl.replace(/\/+$/, '');
+        if (!canonicalHref.startsWith(origin)) {
+            add(`canonical "${canonicalHref}" is not on the configured site origin`);
+        }
+    }
+    // A meta description is required on every indexable page.
+    const description = html.match(/<meta\b[^>]*\bname=["']?description["']?[^>]*>/i)?.[0];
+    const descriptionContent = description?.match(/\bcontent=["']([^"']*)["']/i)?.[1];
+    if (!description) {
+        if (!noindex)
+            add('no meta description');
+    }
+    else if (!descriptionContent?.trim())
+        add('meta description is empty');
+    // Structured data must exist and must be valid JSON — a syntax error there is
+    // silently ignored by crawlers, so it has to be asserted.
+    const jsonLdBlocks = [
+        ...html.matchAll(/<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)
+    ];
+    if (jsonLdBlocks.length === 0 && !noindex) {
+        add('no application/ld+json block');
+    }
+    for (const [index, block] of jsonLdBlocks.entries()) {
+        try {
+            JSON.parse(block[1]);
+        }
+        catch (error) {
+            add(`JSON-LD block ${index + 1} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Exactly one <h1>: the page template owns it, and content must not add one.
+    const h1Count = countMatches(html, /<h1\b/gi);
+    if (h1Count === 0)
+        add('no <h1>');
+    if (h1Count > 1)
+        add(`${h1Count} <h1> tags — expected exactly one`);
+    // <html> must declare a language for both crawlers and screen readers.
+    const lang = html.match(/<html\b[^>]*\blang=["']([^"']*)["']/i)?.[1];
+    if (!lang?.trim())
+        add('<html> has no lang attribute');
+    return issues;
+}