render-pulse 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0 (2026-10-14)
+
+First release, by Louis Wright.
+
+- Head scripts without defer/async/module, synchronous body scripts that block parsing, document.write.
+- Render-blocking stylesheets: gzip budget per page, count, @import chains (files and inline), print CSS without media, stylesheets placed after sync scripts, missing critical CSS.
+- Third-party render-blocking resources without preconnect.
+- Text/JSON/SARIF/Markdown output, `--fail-on`, exit codes 0/1/2, allowlist with expiry, severity overrides.
+- Composite GitHub Action with job summary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Wright
+
+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,181 @@
-# Temporary Holding Version
+# render-pulse
 
-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.
+> Find the CSS and JavaScript that block first paint in your built site, with the defer, async, media or critical-CSS fix for each.
+
+Nothing is painted until the browser has downloaded and parsed every render-blocking stylesheet and synchronous script in `<head>`. One forgotten `<script src>` without `defer`, a 200 kB framework stylesheet or an `@import` chain can add seconds to First Contentful Paint and LCP on mobile. `render-pulse` reads your static build output, works out which resources are actually on the critical path (respecting `defer`, `async`, `type=module`, `media`, `disabled` and alternate stylesheets) and reports each one with a concrete fix.
+
+CLI, library and GitHub Action. Node.js 18+, **zero runtime dependencies**. Works on any static build output (Astro, Next.js `output: 'export'`, Eleventy, Hugo, Jekyll, Docusaurus, VitePress, plain HTML) and runs offline: point it at the folder your build writes. By Louis Wright.
+
+## Features
+
+- **Scripts:** classic `<script src>` in `<head>` without `defer`/`async` (high), synchronous external scripts in the middle of `<body>`, `document.write()`, scripts placed before stylesheets.
+- **Stylesheets:** gzip size of all render-blocking CSS per page against a budget (default 50 kB), too many blocking stylesheets, `@import` in CSS files or inline styles, print stylesheets without `media="print"`, and a hint to inline critical CSS when blocking CSS exceeds the 14 kB first round trip.
+- **Third parties:** render-blocking resources from other origins without `<link rel="preconnect">`.
+- **Knows the async patterns:** `media="print" onload="this.media='all'"`, module scripts, JSON-LD and template scripts are not reported.
+
+### Scope
+
+render-pulse inspects the HTML and CSS on disk; it does not run a browser. Font loading has its own tool (font-pulse), JavaScript size is bundle-pulse, and lab timings are vitals-pulse.
+
+## Rules
+
+| Rule | Default severity | What it means |
+|---|---|---|
+| `render-blocking-script` | high | Classic <script src> in <head> without defer or async blocks rendering |
+| `render-blocking-css-heavy` | medium | Render-blocking CSS is large (inline the critical CSS, load the rest later) |
+| `render-css-import` | medium | @import in render-blocking CSS serialises downloads |
+| `render-third-party-blocking` | medium | Render-blocking resource from another origin without preconnect |
+| `render-document-write` | medium | document.write() in a script delays parsing and can block on network |
+| `render-parser-blocking-body` | low | Synchronous external <script> in <body> blocks parsing of everything after it |
+| `render-too-many-stylesheets` | low | Many render-blocking stylesheets |
+| `render-print-css-blocking` | low | Print/alternate stylesheet without a matching media attribute blocks rendering |
+| `render-large-inline` | low | Very large inline <style> or <script> in <head> |
+| `render-sync-before-css` | low | Synchronous script placed before stylesheets delays CSS discovery |
+| `render-no-critical-css` | info | Blocking CSS over 14 KB and no inline critical CSS |
+| `allowlist-expired` | medium | An allowlist entry is past its `expires` date |
+| `allowlist-unused` | info | An allowlist entry matched nothing |
+
+## Install and run
+
+```bash
+npx render-pulse dist
+npx render-pulse public --max-css-kb 30 --fail-on medium
+npx render-pulse _site --format sarif > render.sarif
+```
+
+Pages are mapped to URLs the way static hosts serve them: `index.html` → `/`, `blog/index.html` → `/blog/`, `about.html` → `/about.html` (or `/about` with `--clean-urls`). Pass `--base-url` with your public URL, or let it be inferred from canonical / `og:url` tags. Meta-refresh redirect stubs and `404.html` are skipped. `X-Robots-Tag` and `Link` headers are read from Netlify/Cloudflare `_headers` and `vercel.json`.
+
+### Sample output
+
+```text
+render-pulse — https://example.com
+1 page(s) at https://example.com
+
+HIGH     index.html:2 /: <script src="/js/jquery.js"> (0.0 KB gzip) in <head> blocks rendering [render-blocking-script]
+HIGH     index.html:7 /: <script src="https://tags.example.org/t.js"> in <head> blocks rendering [render-blocking-script]
+MEDIUM   css/all.css css/all.css uses @import [render-css-import]
+MEDIUM   index.html /: render-blocking resource from https://fonts.example.org without <link rel="preconnect"> [render-third-party-blocking]
+MEDIUM   index.html /: render-blocking resource from https://tags.example.org without <link rel="preconnect"> [render-third-party-blocking]
+MEDIUM   index.html /: 56.2 KB gzip (195.4 KB raw) of render-blocking CSS (budget 50.0 KB) [render-blocking-css-heavy]
+```
+
+## Options
+
+```text
+render-pulse 1.0.0 — find render-blocking CSS and JS in your built site
+
+Usage: render-pulse [site-dir] [options]
+
+Site
+      --base-url <url>        Public URL of the site, e.g. https://example.com (default: inferred from canonical/og:url)
+      --include <globs>       Only check these pages (file or URL path globs, comma-separated)
+      --exclude <globs>       Skip these pages
+      --clean-urls            Pages are served without .html (about.html -> /about)
+Render
+      --max-css-kb <n>         Render-blocking CSS budget per page, gzip KB (default 50)
+
+Common
+  -c, --config <file>     JSON config (default: .render-pulse.json or "renderPulse" in package.json)
+  -f, --format <fmt>      text (default) | json | sarif | markdown
+      --json <file>       Also write a JSON report
+      --sarif <file>      Also write SARIF 2.1.0
+      --markdown <file>   Also write Markdown (e.g. for a job summary)
+      --fail-on <sev>     critical | high | medium | low | info | none (default: high)
+      --list-rules        Print rules and default severities
+      --no-fixes          Hide fix suggestions in text output
+      --no-color          Disable colours
+  -v, --version / -h, --help
+
+Exit codes: 0 = passed, 1 = findings at or above --fail-on, 2 = usage, config or read error.
+```
+
+## Configuration and allowlist
+
+Options can live in `.render-pulse.json` (or a `"renderPulse"` key in `package.json`, or `--config <file>`):
+
+```json
+{
+  "failOn": "medium",
+  "severity": {
+    "render-blocking-script": "low"
+  },
+  "allowlist": [
+    {
+      "rule": "render-blocking-script",
+      "subject": "/js/consent-loader.js",
+      "reason": "Consent manager must run before other tags",
+      "expires": "2027-03-31"
+    }
+  ],
+  "maxCss": 40960,
+  "maxStylesheets": 2,
+  "maxInline": 30720,
+  "exclude": [
+    "/legacy/**"
+  ]
+}
+```
+
+- **`severity`** changes a rule's severity, or turns it `"off"`.
+- **`allowlist`** entries suppress matching findings. Each needs a `reason` and matches on any combination of `rule`, `file`, `subject` (globs with `*`) and `match` (a substring of the message). Add `expires` (`YYYY-MM-DD`) so the exception is time-boxed: once it lapses the finding comes back along with an `allowlist-expired` finding (medium). Entries that no longer match anything are reported as `allowlist-unused` (info).
+
+Config can also set `baseUrl`, `include`, `exclude` and `cleanUrls`. The config file is looked up in the site directory first, then in the current directory, so `.render-pulse.json` can live at your repository root. Other keys: `maxCss` (bytes gzip), `maxStylesheets` (default 3), `maxInline` (default 50 kB), plus `baseUrl`, `include`, `exclude` and `cleanUrls`.
+
+## Output and exit codes
+
+- `--format text` (default), `json`, `sarif` (SARIF 2.1.0 for GitHub code scanning) or `markdown` (for job summaries and PR comments). `--json`, `--sarif` and `--markdown` write extra report files in the same run.
+- `--fail-on <severity>` sets the threshold (`critical`, `high`, `medium`, `low`, `info`, `none`; default `high`).
+- Exit codes: **0** passed, **1** findings at or above `--fail-on`, **2** usage, config or read error.
+
+## GitHub Action
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # only needed for the SARIF upload
+jobs:
+  render-pulse:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with: { persist-credentials: false }
+      - run: npm ci && npm run build   # produce the static site first
+      - uses: MrLouisWright/render-pulse@v1
+        with:
+          path: dist
+          fail-on: high
+          sarif: render-pulse.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with: { sarif_file: render-pulse.sarif }
+```
+
+| Input | Description | Default |
+|---|---|---|
+| `path` | Built site directory (e.g. dist, public, _site) | `.` |
+| `base-url` | Public URL of the site, e.g. https://example.com | |
+| `fail-on` | Failure threshold | `high` |
+| `config` | Config file path | |
+| `sarif` / `json` | Write SARIF / JSON report to this path | |
+| `job-summary` | Add the Markdown report to the job summary | `true` |
+| `args` | Extra CLI arguments | |
+
+The action runs the bundled CLI with Node 20; it has no dependencies to install. Pin it to a commit SHA if your policy requires it.
+
+## Library
+
+```js
+import { check, blocksRender } from "render-pulse";
+blocksRender({ rel: "stylesheet", media: "print" }); // false
+const report = check("dist", { maxCss: 30 * 1024 });
+```
+
+Types are included.
+
+## Requirements
+
+Node.js 18 or newer. Zero runtime dependencies.
+
+## Licence
+
+MIT © Louis Wright. See [LICENSE](LICENSE).

package/action.yml

@@ -0,0 +1,47 @@
+name: 'render-pulse'
+description: 'Find render-blocking CSS and JS in your built site'
+author: 'Louis Wright'
+branding: { icon: 'alert-triangle', color: 'blue' }
+inputs:
+  path: { description: 'Built site directory (e.g. dist, public, _site)', default: '.' }
+  base-url: { description: 'Public URL of the site, e.g. https://example.com', default: '' }
+  fail-on: { description: 'critical | high | medium | low | info | none', default: 'high' }
+  config: { description: 'Path to JSON config file', default: '' }
+  sarif: { description: 'Write SARIF to this path', default: '' }
+  json: { description: 'Write JSON report to this path', default: '' }
+  job-summary: { description: 'Write the Markdown report to the job summary (true/false)', default: 'true' }
+  args: { description: 'Extra CLI arguments', default: '' }
+outputs:
+  markdown-file: { description: 'Path of the Markdown report', value: '${{ steps.run.outputs.markdown-file }}' }
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with: { node-version: '20' }
+    - id: run
+      shell: bash
+      env:
+        XB_PATH: ${{ inputs.path }}
+        XB_BASE_URL: ${{ inputs.base-url }}
+        XB_FAIL_ON: ${{ inputs.fail-on }}
+        XB_CONFIG: ${{ inputs.config }}
+        XB_SARIF: ${{ inputs.sarif }}
+        XB_JSON: ${{ inputs.json }}
+        XB_SUMMARY: ${{ inputs.job-summary }}
+        XB_ARGS: ${{ inputs.args }}
+        XB_BIN: ${{ github.action_path }}/bin/render-pulse.js
+      run: |
+        md="$RUNNER_TEMP/render-pulse.md"
+        args=("$XB_PATH" --fail-on "$XB_FAIL_ON" --markdown "$md")
+        [ -n "$XB_BASE_URL" ] && args+=(--base-url "$XB_BASE_URL")
+        [ -n "$XB_CONFIG" ] && args+=(--config "$XB_CONFIG")
+        [ -n "$XB_SARIF" ] && args+=(--sarif "$XB_SARIF")
+        [ -n "$XB_JSON" ] && args+=(--json "$XB_JSON")
+        set +e
+        # shellcheck disable=SC2086
+        node "$XB_BIN" "${args[@]}" $XB_ARGS
+        code=$?
+        set -e
+        echo "markdown-file=$md" >> "$GITHUB_OUTPUT"
+        if [ "$XB_SUMMARY" = "true" ] && [ -f "$md" ]; then cat "$md" >> "$GITHUB_STEP_SUMMARY"; fi
+        exit $code

package/bin/render-pulse.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { mainCli, check, RULES, SITE_OPTIONS, SITE_HELP } from '../src/index.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+mainCli({
+  name: 'render-pulse', version: pkg.version, configKey: 'renderPulse', rules: RULES,
+  tagline: 'find render-blocking CSS and JS in your built site',
+  usage: 'Usage: render-pulse [site-dir] [options]',
+  help: `${SITE_HELP}Render
+      --max-css-kb <n>         Render-blocking CSS budget per page, gzip KB (default 50)
+`,
+  options: { ...SITE_OPTIONS, 'max-css-kb': { type: 'string' } },
+  run: async ({ dir, values: o, config, configFile }) => check(dir, { cli: o, maxCss: o['max-css-kb'] != null ? Number(o['max-css-kb']) * 1024 : undefined, toolVersion: pkg.version }, config, configFile),
+});

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "render-pulse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Find render-blocking resources in a built static site: head scripts without defer/async, heavy blocking CSS, @import chains, third-party blocking resources without preconnect, document.write, parser-blocking body scripts, print CSS without media, missing critical CSS. SARIF, GitHub Action. Zero deps.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "render-pulse": "bin/render-pulse.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "action.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "render-blocking",
+    "critical-css",
+    "performance",
+    "defer",
+    "async",
+    "fcp",
+    "lcp",
+    "core-web-vitals",
+    "static-site",
+    "github-action"
+  ],
+  "author": "Louis Wright <hello@louiswright.co.uk> (https://github.com/MrLouisWright)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrLouisWright/render-pulse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MrLouisWright/render-pulse/issues"
+  },
+  "homepage": "https://github.com/MrLouisWright/render-pulse#readme"
+}

package/src/core.d.ts

@@ -0,0 +1,16 @@
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export interface Finding { rule: string; severity: Severity; message: string; fix?: string; file?: string; line?: number; subject?: string; [k: string]: unknown }
+export interface AllowlistEntry { rule?: string; file?: string; subject?: string; match?: string; reason: string; expires?: string }
+export interface Config { failOn?: Severity | 'none'; allowlist?: AllowlistEntry[]; severity?: Record<string, Severity | 'off'>; [k: string]: unknown }
+export interface Rule { severity: Severity; title: string }
+export interface Report { tool: { name: string; version: string; rules: Record<string, Rule> }; target: string; summaryLine?: string; counts: Record<Severity, number>; findings: Finding[]; suppressed: (Finding & { reason: string; expires: string | null })[]; [k: string]: unknown }
+export const SEVERITIES: Severity[];
+export const POLICY_RULES: Record<string, Rule>;
+export class UsageError extends Error {}
+export function applyPolicy(raw: Finding[], config?: Config, opts?: { now?: Date; configFile?: string }): { findings: Finding[]; suppressed: Report['suppressed'] };
+export function validateConfig(config: unknown): Config;
+export function exceeds(report: Report, failOn: Severity | 'none'): boolean;
+export function formatText(report: Report, opts?: { color?: boolean; failOn?: string; fixes?: boolean }): string;
+export function formatJson(report: Report): string;
+export function formatSarif(report: Report): string;
+export function formatMarkdown(report: Report, opts?: { failOn?: string }): string;

package/src/core.js

@@ -0,0 +1,176 @@
+// Shared reporting / policy / CLI core. Zero dependencies. Louis Wright, MIT.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+export const sevRank = (s) => { const i = SEVERITIES.indexOf(s); return i === -1 ? 99 : i; };
+export class UsageError extends Error {}
+
+export const POLICY_RULES = {
+  'allowlist-expired': { severity: 'medium', title: 'Allowlist entry has expired' },
+  'allowlist-unused': { severity: 'info', title: 'Allowlist entry matched nothing' },
+};
+
+function globRe(p) { return new RegExp('^' + String(p).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i'); }
+
+/** Does an allowlist entry ({rule, file, match, subject}) cover a finding? */
+export function entryMatches(e, f) {
+  if (e.rule && !globRe(e.rule).test(f.rule)) return false;
+  if (e.file && !globRe(e.file).test(f.file || '')) return false;
+  if (e.subject && !globRe(e.subject).test(f.subject || '')) return false;
+  if (e.match && !String(f.message).toLowerCase().includes(String(e.match).toLowerCase())) return false;
+  return !!(e.rule || e.file || e.subject || e.match);
+}
+
+export function validateConfig(config) {
+  if (config == null || typeof config !== 'object' || Array.isArray(config)) throw new UsageError('config must be a JSON object');
+  if (config.allowlist != null && !Array.isArray(config.allowlist)) throw new UsageError('"allowlist" must be an array');
+  for (const [i, e] of (config.allowlist || []).entries()) {
+    if (!e || typeof e !== 'object') throw new UsageError(`allowlist[${i}] must be an object`);
+    if (!e.rule && !e.file && !e.subject && !e.match) throw new UsageError(`allowlist[${i}] needs at least one of rule, file, subject, match`);
+    if (!e.reason) throw new UsageError(`allowlist[${i}] needs a "reason"`);
+    if (e.expires != null && (!/^\d{4}-\d{2}-\d{2}$/.test(e.expires) || Number.isNaN(Date.parse(e.expires)))) throw new UsageError(`allowlist[${i}].expires must be YYYY-MM-DD`);
+  }
+  for (const [k, v] of Object.entries(config.severity || {})) if (v !== 'off' && !SEVERITIES.includes(v)) throw new UsageError(`severity.${k} must be one of ${SEVERITIES.join(', ')}, off`);
+  return config;
+}
+
+/** Apply severity overrides and the allowlist. Returns { findings, suppressed }. */
+export function applyPolicy(raw, config = {}, { now = new Date(), configFile = 'config' } = {}) {
+  const today = now.toISOString().slice(0, 10);
+  const sev = config.severity || {};
+  const list = (config.allowlist || []).map((e, i) => ({ ...e, index: i, used: 0, expired: !!(e.expires && e.expires < today) }));
+  const findings = []; const suppressed = [];
+  for (const f0 of raw) {
+    const o = sev[f0.rule];
+    if (o === 'off') continue;
+    const f = o ? { ...f0, severity: o } : f0;
+    const hit = list.find((e) => entryMatches(e, f));
+    if (hit) { hit.used++; if (!hit.expired) { suppressed.push({ ...f, reason: hit.reason, expires: hit.expires || null }); continue; } }
+    findings.push(f);
+  }
+  for (const e of list) {
+    const label = [e.rule, e.file, e.subject, e.match].filter(Boolean).join(' / ');
+    if (e.expired && sev['allowlist-expired'] !== 'off') findings.push({ rule: 'allowlist-expired', severity: sev['allowlist-expired'] || 'medium', file: configFile, message: `Allowlist entry #${e.index + 1} (${label}) expired on ${e.expires}`, fix: 'Fix the underlying finding, or renew the entry with a new "expires" date and reason.' });
+    else if (!e.used && sev['allowlist-unused'] !== 'off') findings.push({ rule: 'allowlist-unused', severity: sev['allowlist-unused'] || 'info', file: configFile, message: `Allowlist entry #${e.index + 1} (${label}) matched no finding`, fix: 'Remove the stale entry.' });
+  }
+  findings.sort((a, b) => sevRank(a.severity) - sevRank(b.severity) || String(a.file || '').localeCompare(String(b.file || '')) || (a.line || 0) - (b.line || 0));
+  return { findings, suppressed };
+}
+
+export function countBy(findings) { const c = {}; for (const s of SEVERITIES) c[s] = 0; for (const f of findings) c[f.severity] = (c[f.severity] || 0) + 1; return c; }
+export const exceeds = (r, failOn) => !!failOn && failOn !== 'none' && r.findings.some((f) => sevRank(f.severity) <= sevRank(failOn));
+
+const C = { critical: '\x1b[35;1m', high: '\x1b[31;1m', medium: '\x1b[33m', low: '\x1b[36m', info: '\x1b[2m', dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m', red: '\x1b[31m', green: '\x1b[32m' };
+const sumText = (counts) => SEVERITIES.filter((k) => counts[k]).map((k) => `${counts[k]} ${k}`).join(', ') || 'no findings';
+const loc = (f) => (f.file ? `${f.file}${f.line ? ':' + f.line : ''}` : '');
+
+export function formatText(r, { color = false, failOn, fixes = true } = {}) {
+  const c = (k, s) => (color ? `${C[k]}${s}${C.reset}` : s);
+  const l = [c('bold', `${r.tool.name} — ${r.target}`)];
+  if (r.summaryLine) l.push(c('dim', r.summaryLine));
+  l.push('');
+  for (const f of r.findings) {
+    l.push(`${c(f.severity, f.severity.toUpperCase().padEnd(8))} ${loc(f) ? c('dim', loc(f) + ' ') : ''}${f.message} [${f.rule}]`);
+    if (fixes && f.fix) l.push(c('dim', `         ↳ fix: ${f.fix}`));
+  }
+  if (r.findings.length) l.push('');
+  if (r.suppressed.length) l.push(c('dim', `${r.suppressed.length} finding(s) covered by the allowlist`));
+  l.push(sumText(r.counts));
+  if (failOn) l.push(exceeds(r, failOn) ? c('red', `✖ Failing (fail-on: ${failOn}).`) : c('green', `✔ Passing (fail-on: ${failOn}).`));
+  return l.join('\n') + '\n';
+}
+
+export const formatJson = (r) => JSON.stringify(r, null, 2) + '\n';
+
+const LEVEL = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'note' };
+const SCORE = { critical: '9.0', high: '7.5', medium: '5.0', low: '3.0', info: '1.0' };
+export function formatSarif(r) {
+  const rules = { ...r.tool.rules, ...POLICY_RULES };
+  const ids = Object.keys(rules);
+  const repo = `https://github.com/MrLouisWright/${r.tool.name}`;
+  return JSON.stringify({
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json', version: '2.1.0',
+    runs: [{
+      tool: { driver: { name: r.tool.name, version: r.tool.version, informationUri: repo, rules: ids.map((id) => ({ id, name: id.replace(/(^|-)(\w)/g, (_, __, ch) => ch.toUpperCase()), shortDescription: { text: rules[id].title }, helpUri: `${repo}#rules`, defaultConfiguration: { level: LEVEL[rules[id].severity] }, properties: { 'security-severity': SCORE[rules[id].severity] } })) } },
+      results: r.findings.map((f) => ({ ruleId: f.rule, ruleIndex: ids.indexOf(f.rule), level: LEVEL[f.severity], message: { text: f.fix ? `${f.message}. Fix: ${f.fix}` : f.message }, locations: [{ physicalLocation: { artifactLocation: { uri: f.file || r.tool.defaultFile || '.' }, region: { startLine: f.line || 1 } } }], partialFingerprints: { ruleSubject: `${f.rule}:${f.file || ''}:${f.subject || f.message}` }, properties: { severity: f.severity } })),
+    }],
+  }, null, 2) + '\n';
+}
+
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+export function formatMarkdown(r, { failOn } = {}) {
+  const l = [`## ${r.tool.emoji || '📏'} ${r.tool.name}`, '', `**${esc(r.target)}**: ${r.summaryLine ? esc(r.summaryLine) + '; ' : ''}${sumText(r.counts)}.`];
+  if (failOn) l.push('', exceeds(r, failOn) ? `❌ Failing at \`--fail-on ${failOn}\`.` : `✅ Passing at \`--fail-on ${failOn}\`.`);
+  if (r.findings.length) {
+    l.push('', '| Severity | Location | Rule | Finding | Fix |', '|---|---|---|---|---|');
+    for (const f of r.findings) l.push(`| ${f.severity} | ${loc(f) ? '`' + esc(loc(f)) + '`' : ''} | \`${f.rule}\` | ${esc(f.message)} | ${esc(f.fix)} |`);
+  }
+  if (r.suppressed.length) l.push('', `_${r.suppressed.length} finding(s) covered by the allowlist._`);
+  return l.join('\n') + '\n';
+}
+
+/** Build a report object from raw findings. */
+export function buildReport(tool, target, raw, config, extra = {}) {
+  const { findings, suppressed } = applyPolicy(raw, config, { now: extra.now, configFile: extra.configFile });
+  const { now, configFile, ...rest } = extra;
+  return { tool: { name: tool.name, version: tool.version, rules: tool.rules, emoji: tool.emoji, defaultFile: tool.defaultFile }, target, ...rest, counts: countBy(findings), findings, suppressed };
+}
+
+export function loadConfig(dir, name, key, explicit) {
+  const file = explicit ? resolve(explicit) : join(dir, `.${name}.json`);
+  if (explicit || existsSync(file)) {
+    let c; try { c = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new UsageError(`Cannot read config ${file}: ${e.message}`); }
+    return { config: validateConfig(c), configFile: explicit || `.${name}.json` };
+  }
+  for (const d of [dir, process.cwd()]) {
+    if (d !== dir && existsSync(join(d, `.${name}.json`))) return loadConfig(d, name, key, join(d, `.${name}.json`));
+    try { const pj = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')); if (pj[key]) return { config: validateConfig(pj[key]), configFile: 'package.json' }; } catch (e) { if (e instanceof UsageError) throw e; }
+  }
+  return { config: {}, configFile: null };
+}
+
+const list = (v) => (v || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+export { list as splitList };
+
+/**
+ * Generic CLI. spec = { name, version, configKey, rules, help (tool-specific options text), options (parseArgs), defaultFailOn,
+ *   run: async ({ dir, positionals, values, config, configFile, stdin }) => report }
+ */
+export async function runCli(spec, argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  const usage = (m) => { io.stderr.write(`${spec.name}: ${m}\nRun with --help for usage.\n`); return 2; };
+  let a;
+  try {
+    a = parseArgs({ args: argv, allowPositionals: true, options: { ...spec.options, config: { type: 'string', short: 'c' }, format: { type: 'string', short: 'f' }, json: { type: 'string' }, sarif: { type: 'string' }, markdown: { type: 'string' }, 'fail-on': { type: 'string' }, 'no-color': { type: 'boolean' }, 'no-fixes': { type: 'boolean' }, 'list-rules': { type: 'boolean' }, version: { type: 'boolean', short: 'v' }, help: { type: 'boolean', short: 'h' } } });
+  } catch (e) { return usage(e.message); }
+  const { values: o, positionals } = a;
+  const all = { ...spec.rules, ...POLICY_RULES };
+  if (o.help) { io.stdout.write(`${spec.name} ${spec.version} — ${spec.tagline}\n\n${spec.usage}\n\n${spec.help}\nCommon\n  -c, --config <file>     JSON config (default: .${spec.name}.json or "${spec.configKey}" in package.json)\n  -f, --format <fmt>      text (default) | json | sarif | markdown\n      --json <file>       Also write a JSON report\n      --sarif <file>      Also write SARIF 2.1.0\n      --markdown <file>   Also write Markdown (e.g. for a job summary)\n      --fail-on <sev>     critical | high | medium | low | info | none (default: ${spec.defaultFailOn || 'high'})\n      --list-rules        Print rules and default severities\n      --no-fixes          Hide fix suggestions in text output\n      --no-color          Disable colours\n  -v, --version / -h, --help\n\nExit codes: 0 = passed, 1 = findings at or above --fail-on, 2 = usage, config or read error.\n`); return 0; }
+  if (o.version) { io.stdout.write(spec.version + '\n'); return 0; }
+  if (o['list-rules']) { for (const [id, r] of Object.entries(all)) io.stdout.write(`${id.padEnd(28)} ${r.severity.padEnd(9)} ${r.title}\n`); return 0; }
+  const format = o.format || 'text';
+  if (!['text', 'json', 'sarif', 'markdown'].includes(format)) return usage(`Invalid --format: ${format}`);
+  let report; let failOn;
+  try {
+    const dir = resolve(spec.dirFrom ? spec.dirFrom(o, positionals) : (positionals[0] || '.'));
+    if (!existsSync(dir)) return usage(`No such directory: ${dir}`);
+    const { config, configFile } = loadConfig(dir, spec.name, spec.configKey, o.config);
+    failOn = o['fail-on'] || config.failOn || spec.defaultFailOn || 'high';
+    if (failOn !== 'none' && !SEVERITIES.includes(failOn)) return usage(`Invalid --fail-on: ${failOn}`);
+    report = await spec.run({ dir, positionals, values: o, config, configFile: configFile || `.${spec.name}.json` });
+  } catch (e) { if (e instanceof UsageError || e.code === 'ENOENT' || e.code === 'EACCES') return usage(e.message); throw e; }
+  const color = !o['no-color'] && io.stdout.isTTY && !process.env.NO_COLOR;
+  const out = { text: () => formatText(report, { color, failOn, fixes: !o['no-fixes'] }), json: () => formatJson(report), sarif: () => formatSarif(report), markdown: () => formatMarkdown(report, { failOn }) };
+  io.stdout.write(out[format]());
+  try {
+    if (o.json) writeFileSync(o.json, formatJson(report));
+    if (o.sarif) writeFileSync(o.sarif, formatSarif(report));
+    if (o.markdown) writeFileSync(o.markdown, formatMarkdown(report, { failOn }));
+  } catch (e) { return usage(`Cannot write output: ${e.message}`); }
+  return exceeds(report, failOn) ? 1 : 0;
+}
+
+export function mainCli(spec) {
+  runCli(spec).then((c) => { process.exitCode = c; }, (e) => { process.stderr.write(`${spec.name}: ${e.stack || e}\n`); process.exitCode = 2; });
+}

package/src/index.d.ts

@@ -0,0 +1,6 @@
+import type { Report, Rule } from './core.js';
+export * from './core.js';
+export interface RenderOptions { baseUrl?: string; include?: string[]; exclude?: string[]; cleanUrls?: boolean; maxCss?: number; toolVersion?: string; now?: Date }
+export declare const RULES: Record<string, Rule>;
+export declare function blocksRender(attrs: Record<string, string>): boolean;
+export declare function check(dir: string, opts?: RenderOptions, config?: Record<string, unknown>, configFile?: string): Report;

package/src/index.js

@@ -0,0 +1,90 @@
+// render-pulse: find render-blocking CSS and JS in the critical path of a built static site and suggest
+// defer/async/media/critical-CSS fixes. Zero dependencies. Louis Wright, MIT.
+import { gzipSync } from 'node:zlib';
+import { runBeacon, finder } from './site.js';
+import { buildReport, UsageError } from './core.js';
+
+export * from './core.js';
+export { loadSite, parseHtml, SITE_OPTIONS, SITE_HELP } from './site.js';
+
+export const RULES = {
+  'render-blocking-script': { severity: 'high', title: 'Classic <script src> in <head> without defer or async blocks rendering' },
+  'render-blocking-css-heavy': { severity: 'medium', title: 'Render-blocking CSS is large (inline the critical CSS, load the rest later)' },
+  'render-css-import': { severity: 'medium', title: '@import in render-blocking CSS serialises downloads' },
+  'render-third-party-blocking': { severity: 'medium', title: 'Render-blocking resource from another origin without preconnect' },
+  'render-document-write': { severity: 'medium', title: 'document.write() in a script delays parsing and can block on network' },
+  'render-parser-blocking-body': { severity: 'low', title: 'Synchronous external <script> in <body> blocks parsing of everything after it' },
+  'render-too-many-stylesheets': { severity: 'low', title: 'Many render-blocking stylesheets' },
+  'render-print-css-blocking': { severity: 'low', title: 'Print/alternate stylesheet without a matching media attribute blocks rendering' },
+  'render-large-inline': { severity: 'low', title: 'Very large inline <style> or <script> in <head>' },
+  'render-sync-before-css': { severity: 'low', title: 'Synchronous script placed before stylesheets delays CSS discovery' },
+  'render-no-critical-css': { severity: 'info', title: 'Blocking CSS over 14 KB and no inline critical CSS' },
+};
+const kb = (n) => `${(n / 1024).toFixed(1)} KB`;
+const gz = (s) => gzipSync(Buffer.from(s)).length;
+const isJsType = (t) => !t || /^(text|application)\/(java|ecma)script$|^module$/i.test(t.trim());
+/** True when a <link rel=stylesheet> blocks rendering for screen. */
+export function blocksRender(attrs) {
+  if (attrs.disabled != null) return false; const rel = (attrs.rel || '').toLowerCase();
+  if (/\balternate\b/.test(rel)) return false;
+  const media = (attrs.media || 'all').toLowerCase().trim();
+  if (/^print$/.test(media) || /\bprint\b/.test(media) && !/\b(all|screen)\b/.test(media)) return false;
+  if (/^\(prefers-color-scheme/.test(media) || /orientation|min-width|max-width/.test(media)) return true; // conservative: may match
+  return true;
+}
+
+function analyze(site, opts, config) {
+  const { findings, add } = finder(RULES);
+  const cssBudget = opts.maxCss ?? config.maxCss ?? 50 * 1024; const maxSheets = config.maxStylesheets ?? 3; const inlineMax = config.maxInline ?? 50 * 1024;
+  const cache = new Map();
+  const local = (u) => { if (!u || !site.isInternal(u)) return null; let p = u.pathname; if (site.basePath && p.startsWith(site.basePath)) p = p.slice(site.basePath.length); try { p = decodeURIComponent(p); } catch { /* keep */ } p = p.replace(/^\/+/, ''); if (!cache.has(p)) { const t = site.read(p); cache.set(p, t); } return { rel: p, text: cache.get(p) }; };
+  let blockingTotal = 0;
+  for (const pg of site.pages) {
+    const doc = pg.doc; const head = doc.all.filter((e) => e.inHead);
+    const preconnect = new Set(doc.links.filter((l) => l.rel.includes('preconnect')).map((l) => { try { return new URL(l.href, 'https://x.invalid').origin; } catch { return ''; } }));
+    const at = (e) => ({ file: pg.file, line: e.line });
+    let sheets = 0; let cssBytes = 0; let cssGz = 0; let seenSyncScript = null; let warnedOrder = false; const third = new Set();
+    const inlineCss = head.filter((e) => e.tag === 'style').reduce((a, e) => a + (e.rawText || '').length, 0);
+    for (const e of head) {
+      const a = e.attrs;
+      if (e.tag === 'script') {
+        const t = a.type; if (!isJsType(t)) continue;
+        if (a.src) {
+          const isModule = /^module$/i.test(t || ''); if (a.async != null || a.defer != null || isModule) continue;
+          const u = site.resolve(pg, a.src); const l = local(u); const size = l?.text != null ? ` (${kb(gz(l.text))} gzip)` : '';
+          add('render-blocking-script', a.src, `${pg.path}: <script src="${a.src}">${size} in <head> blocks rendering`, 'Add defer (keeps order, runs after parsing) or async (independent scripts like analytics), or type="module".', at(e));
+          seenSyncScript ||= e;
+          if (u && !site.isInternal(u) && !preconnect.has(u.origin)) third.add(u.origin);
+        } else if (/document\.write\s*\(/.test(e.rawText || '')) add('render-document-write', `${pg.path}:${e.line}`, `${pg.path}: inline script calls document.write()`, 'Insert elements with DOM APIs instead; Chrome may block document.write-injected scripts on slow connections.', at(e));
+        else if ((e.rawText || '').length > inlineMax) add('render-large-inline', `${pg.path}:${e.line}`, `${pg.path}: inline <script> of ${kb((e.rawText || '').length)} in <head>`, 'Move it to a cached external file with defer.', at(e));
+        continue;
+      }
+      if (e.tag === 'style') { const css = e.rawText || ''; if (css.length > inlineMax) add('render-large-inline', `${pg.path}:${e.line}`, `${pg.path}: inline <style> of ${kb(css.length)} in <head>`, 'Inline only the critical above-the-fold CSS (under ~14 KB); load the rest from a cached file.', at(e)); if (/@import\s/i.test(css)) add('render-css-import', `${pg.path}:${e.line}`, `${pg.path}: inline <style> uses @import`, 'Replace @import with <link rel="stylesheet"> tags so downloads start in parallel.', at(e)); continue; }
+      if (e.tag !== 'link' || !/\bstylesheet\b/i.test(a.rel || '') || !a.href) continue;
+      const u = site.resolve(pg, a.href);
+      if (!blocksRender(a)) continue;
+      if (/(^|[/._-])print([._-]|\.css)/i.test(a.href) && !a.media) add('render-print-css-blocking', a.href, `${pg.path}: ${a.href} looks like a print stylesheet but has no media="print"`, 'Add media="print" so it downloads at low priority without blocking rendering.', at(e));
+      sheets++;
+      if (seenSyncScript && !warnedOrder) { add('render-sync-before-css', a.href, `${pg.path}: stylesheet ${a.href} comes after a synchronous script (line ${seenSyncScript.line})`, 'Put stylesheets before scripts in <head> (or defer the script) so CSS downloads start immediately.', at(e)); warnedOrder = true; }
+      if (u && !site.isInternal(u)) { if (!preconnect.has(u.origin)) third.add(u.origin); continue; }
+      const l = local(u); if (l?.text == null) continue;
+      cssBytes += l.text.length; cssGz += gz(l.text);
+      if (/@import\s/i.test(l.text.replace(/\/\*[\s\S]*?\*\//g, ''))) add('render-css-import', l.rel, `${l.rel} uses @import`, 'Bundle the imported CSS or link it directly, so the browser does not discover it only after downloading this file.', { file: l.rel });
+    }
+    for (const o of third) add('render-third-party-blocking', `${pg.path}|${o}`, `${pg.path}: render-blocking resource from ${o} without <link rel="preconnect">`, `Self-host it, load it without blocking, or add <link rel="preconnect" href="${o}">.`, { file: pg.file });
+    if (sheets > maxSheets) add('render-too-many-stylesheets', pg.path, `${pg.path} has ${sheets} render-blocking stylesheets`, `Combine them (max ${maxSheets}) or load non-critical ones with media/print-onload.`, { file: pg.file });
+    if (cssGz > cssBudget) add('render-blocking-css-heavy', pg.path, `${pg.path}: ${kb(cssGz)} gzip (${kb(cssBytes)} raw) of render-blocking CSS (budget ${kb(cssBudget)})`, 'Inline critical CSS (e.g. critters/beasties) and load the rest asynchronously; remove unused CSS.', { file: pg.file });
+    else if (cssGz > 14 * 1024 && inlineCss < 500) add('render-no-critical-css', pg.path, `${pg.path}: ${kb(cssGz)} gzip of blocking CSS and no inline critical CSS`, 'Consider inlining above-the-fold CSS so first paint needs only the HTML round trip.', { file: pg.file });
+    blockingTotal += cssGz;
+    for (const e of doc.all) if (!e.inHead && e.tag === 'script' && e.attrs.src && isJsType(e.attrs.type) && !/^module$/i.test(e.attrs.type || '') && e.attrs.async == null && e.attrs.defer == null) {
+      const after = doc.all.indexOf(e); const rest = doc.all.slice(after + 1).filter((x) => !['script', 'noscript', 'template', 'style', 'link'].includes(x.tag) && x.tag !== '#document').length;
+      if (rest > 5) add('render-parser-blocking-body', e.attrs.src, `${pg.path}: synchronous <script src="${e.attrs.src}"> in <body> before ${rest} more elements`, 'Move it to the end of <body> or add defer/async.', at(e));
+    }
+  }
+  return { findings, info: { blockingCssGzip: blockingTotal } };
+}
+
+export function check(dir, opts = {}, config = {}, configFile) {
+  const tool = { name: 'render-pulse', version: opts.toolVersion || '1.0.0', rules: RULES, emoji: '🚦', defaultFile: 'index.html' };
+  return runBeacon(tool, dir, { ...opts, UsageError }, config, configFile, analyze, buildReport);
+}

package/src/site.js

@@ -0,0 +1,326 @@
+// Shared static-site reader for the *-beacon packages: a small, forgiving HTML parser,
+// a build-output walker that maps files to URLs, and _headers / vercel.json header rules.
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const RAW = new Set(['script', 'style', 'textarea', 'title', 'xmp', 'noscript', 'template']);
+const HEADISH = new Set(['html', 'head', 'meta', 'link', 'title', 'base', 'script', 'style', 'noscript', 'template']);
+const BLOCK = new Set(['address', 'article', 'aside', 'blockquote', 'br', 'dd', 'details', 'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'summary', 'table', 'td', 'th', 'tr', 'ul', 'option', 'caption']);
+const CLOSES_P = new Set(['address', 'article', 'aside', 'blockquote', 'details', 'div', 'dl', 'fieldset', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'table', 'ul']);
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00a0', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', copy: '©', reg: '®', trade: '™', laquo: '«', raquo: '»', middot: '·', bull: '•', times: '×', eacute: 'é', egrave: 'è', aacute: 'á', uuml: 'ü', ouml: 'ö', auml: 'ä', szlig: 'ß', ccedil: 'ç', ntilde: 'ñ', euro: '€', pound: '£', yen: '¥', deg: '°', shy: '' };
+export const decode = (s) => String(s).replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);?/gi, (m, e) => { if (e[0] === '#') { const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10); try { return String.fromCodePoint(n); } catch { return m; } } const v = ENT[e.toLowerCase()]; return v ?? m; });
+export const squash = (s) => String(s).replace(/[\s\u00a0]+/g, ' ').trim();
+
+function parseAttrs(src) {
+  const attrs = {};
+  for (const m of src.matchAll(/([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g)) { const k = m[1].toLowerCase(); if (!(k in attrs)) attrs[k] = decode(m[2] ?? m[3] ?? m[4] ?? ''); }
+  return attrs;
+}
+
+/** Parse HTML into a light tree. Elements: { tag, attrs, line, children, parent, inHead }. Text nodes: { text }. */
+export function parseHtml(html) {
+  html = String(html).replace(/^\uFEFF/, '');
+  const root = { tag: '#document', attrs: {}, children: [], line: 1, parent: null };
+  const all = []; let cur = root; let bodyStarted = false; let i = 0; let line = 1;
+  const lineAt = (to) => { for (let k = i; k < to; k++) if (html.charCodeAt(k) === 10) line++; i = to; };
+  const inHeadEl = () => { for (let n = cur; n; n = n.parent) if (n.tag === 'head') return true; return false; };
+  const close = (tag) => { for (let n = cur; n && n !== root; n = n.parent) if (n.tag === tag) { cur = n.parent; return true; } return false; };
+  const open = (tag, attrs, ln, selfClose) => {
+    if (tag === 'body') bodyStarted = true;
+    else if (!HEADISH.has(tag) && !inHeadEl()) bodyStarted = true;
+    if (cur.tag === 'head' && !HEADISH.has(tag)) cur = cur.parent; // implicit </head>
+    if (CLOSES_P.has(tag)) { for (let n = cur; n && n !== root && !['div', 'section', 'article', 'main', 'body', 'td', 'li', 'blockquote'].includes(n.tag) || n === cur; n = n.parent) { if (n === root) break; if (n.tag === 'p') { cur = n.parent; break; } if (n !== cur) break; } }
+    if (tag === 'li') { for (let n = cur; n && n !== root; n = n.parent) { if (n.tag === 'li') { cur = n.parent; break; } if (n.tag === 'ul' || n.tag === 'ol') break; } }
+    if (tag === 'dt' || tag === 'dd') { for (let n = cur; n && n !== root; n = n.parent) { if (n.tag === 'dt' || n.tag === 'dd') { cur = n.parent; break; } if (n.tag === 'dl') break; } }
+    if (tag === 'option' && cur.tag === 'option') cur = cur.parent;
+    if ((tag === 'tr' || tag === 'td' || tag === 'th') && (cur.tag === 'td' || cur.tag === 'th')) cur = cur.parent;
+    if (tag === 'tr' && cur.tag === 'tr') cur = cur.parent;
+    const el = { tag, attrs, line: ln, children: [], parent: cur, inHead: !bodyStarted || inHeadEl() };
+    cur.children.push(el); all.push(el);
+    if (!VOID.has(tag) && !selfClose) cur = el;
+    return el;
+  };
+  while (i < html.length) {
+    const lt = html.indexOf('<', i);
+    if (lt === -1) { const t = html.slice(i); if (t.trim() && !inHeadEl()) bodyStarted = true; cur.children.push({ text: decode(t) }); lineAt(html.length); break; }
+    if (lt > i) { const t = html.slice(i, lt); if (t.trim()) { if (!inHeadEl() && cur.tag !== 'html' || cur.tag === 'html' || cur === root) { if (!inHeadEl()) bodyStarted = true; } } cur.children.push({ text: decode(t) }); lineAt(lt); }
+    if (html.startsWith('<!--', lt)) { const e = html.indexOf('-->', lt + 4); lineAt(e === -1 ? html.length : e + 3); continue; }
+    if (html[lt + 1] === '!' || html[lt + 1] === '?') { const e = html.indexOf('>', lt); lineAt(e === -1 ? html.length : e + 1); continue; }
+    const m = /^<(\/?)([a-zA-Z][a-zA-Z0-9:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/.exec(html.slice(lt, lt + 20000));
+    if (!m) { cur.children.push({ text: '<' }); lineAt(lt + 1); continue; }
+    const tag = m[2].toLowerCase(); const ln = line;
+    lineAt(lt + m[0].length);
+    if (m[1]) { if (tag === 'p' && !close('p')) { /* stray </p> */ } else if (tag !== 'p') close(tag); continue; }
+    const el = open(tag, parseAttrs(m[3]), ln, /\/\s*$/.test(m[3]));
+    if (RAW.has(tag) && !/\/\s*$/.test(m[3])) {
+      const re = new RegExp(`</${tag}\\s*>`, 'i'); re.lastIndex = 0; const rest = html.slice(i); const em = re.exec(rest);
+      const end = em ? i + em.index : html.length; const raw = html.slice(i, end);
+      if (tag === 'noscript' || tag === 'template') { const inner = parseHtml(raw); for (const c of inner.root.children) { c.parent = el; el.children.push(c); } for (const c of inner.all) { c.line += ln - 1; c.inHead = el.inHead; all.push(c); } }
+      else el.children.push({ text: tag === 'script' || tag === 'style' ? raw : decode(raw), raw: true });
+      el.rawText = raw;
+      lineAt(end); if (em) lineAt(end + em[0].length);
+      cur = el.parent;
+    }
+  }
+  return makeDoc(root, all);
+}
+
+/** Visible text of an element (skips script/style/template, adds spaces at block boundaries). opts.alt includes img alt text. */
+export function textOf(node, opts = {}) {
+  const out = [];
+  const walk = (n) => {
+    if (n.text != null) { if (!n.raw || (n.parent?.tag !== 'script' && n.parent?.tag !== 'style')) out.push(n.text); return; }
+    if (n.tag === 'script' || n.tag === 'style' || n.tag === 'template' || (n.tag === 'noscript' && !opts.noscript)) return;
+    if (opts.skip && opts.skip.has(n.tag)) return;
+    if (n.attrs?.hidden != null || n.attrs?.['aria-hidden'] === 'true' && opts.skipHidden) return;
+    if (n.tag === 'img' && opts.alt) out.push(` ${n.attrs.alt || ''} `);
+    if (BLOCK.has(n.tag)) out.push(' ');
+    for (const c of n.children || []) walk(c);
+    if (BLOCK.has(n.tag)) out.push(' ');
+  };
+  if (node.text != null) return squash(node.text);
+  for (const c of node.children || []) walk(c);
+  return squash(out.join(''));
+}
+const has = (el, tag) => { for (let n = el.parent; n; n = n.parent) if (n.tag === tag) return true; return false; };
+export const ancestor = (el, pred) => { for (let n = el.parent; n; n = n.parent) if (n.tag && pred(n)) return n; return null; };
+
+function makeDoc(root, all) {
+  const doc = { root, all };
+  const by = (t) => all.filter((e) => e.tag === t);
+  doc.find = (t) => by(t);
+  const html = all.find((e) => e.tag === 'html');
+  doc.lang = html?.attrs.lang ?? null;
+  doc.titles = by('title').filter((e) => !has(e, 'svg')).map((e) => ({ text: squash(decode(e.rawText ?? textOf(e))), line: e.line, inHead: e.inHead, el: e }));
+  doc.title = doc.titles.find((t) => t.inHead)?.text ?? doc.titles[0]?.text ?? null;
+  doc.metas = by('meta').map((e) => ({ name: (e.attrs.name || '').toLowerCase() || null, property: (e.attrs.property || '').toLowerCase() || null, httpEquiv: (e.attrs['http-equiv'] || '').toLowerCase() || null, content: e.attrs.content ?? null, charset: e.attrs.charset ?? null, itemprop: e.attrs.itemprop ?? null, line: e.line, inHead: e.inHead, el: e }));
+  doc.meta = (key) => { key = key.toLowerCase(); return doc.metas.filter((m) => m.name === key || m.property === key); };
+  doc.metaContent = (key) => { const m = doc.meta(key).find((x) => x.inHead) || doc.meta(key)[0]; return m ? (m.content ?? '') : null; };
+  doc.links = by('link').map((e) => ({ rel: (e.attrs.rel || '').toLowerCase().split(/\s+/).filter(Boolean), href: e.attrs.href ?? null, hreflang: e.attrs.hreflang ?? null, type: e.attrs.type ?? null, line: e.line, inHead: e.inHead, el: e }));
+  doc.base = by('base').find((e) => e.attrs.href)?.attrs.href ?? null;
+  doc.anchors = by('a').filter((e) => e.attrs.href != null).map((e) => ({ href: e.attrs.href, rel: (e.attrs.rel || '').toLowerCase().split(/\s+/).filter(Boolean), text: textOf(e, { alt: true }), line: e.line, el: e }));
+  doc.headings = [];
+  for (const e of all) {
+    let level = /^h([1-6])$/.exec(e.tag)?.[1];
+    if (!level && e.attrs.role === 'heading') level = e.attrs['aria-level'] || '2';
+    if (level && !has(e, 'svg') && !has(e, 'template')) doc.headings.push({ level: +level, text: textOf(e, { alt: true }), line: e.line, el: e, hidden: e.attrs.hidden != null || !!ancestor(e, (n) => n.attrs?.hidden != null) });
+  }
+  doc.jsonld = by('script').filter((e) => /^application\/ld\+json$/i.test((e.attrs.type || '').trim())).map((e) => { const raw = e.rawText ?? ''; try { return { raw, line: e.line, data: JSON.parse(raw.trim().replace(/^<!--|-->$/g, '')) }; } catch (err) { return { raw, line: e.line, error: err.message }; } });
+  const body = by('body')[0] || root;
+  let _text; let _main;
+  Object.defineProperty(doc, 'text', { get: () => (_text ??= textOf(body)) });
+  Object.defineProperty(doc, 'mainText', { get: () => {
+    if (_main != null) return _main;
+    const mains = all.filter((e) => e.tag === 'main' || e.attrs.role === 'main');
+    const arts = mains.length ? mains : all.filter((e) => e.tag === 'article' && !has(e, 'article'));
+    _main = arts.length ? squash(arts.map((e) => textOf(e, { skip: new Set(['nav', 'aside']) })).join(' ')) : textOf(body, { skip: new Set(['nav', 'header', 'footer', 'aside']) });
+    return _main;
+  } });
+  doc.words = (s) => (s ?? doc.mainText).split(/[^\p{L}\p{N}'’-]+/u).filter((w) => /[\p{L}\p{N}]/u.test(w));
+  doc.robots = (bots = ['robots']) => doc.metas.filter((m) => m.name && bots.includes(m.name)).map((m) => ({ ...m, directives: String(m.content || '').toLowerCase().split(',').map((d) => d.trim()).filter(Boolean) }));
+  return doc;
+}
+
+// ---------------------------------------------------------------------------------------------- site
+export function globToRe(g) {
+  let s = ''; g = String(g);
+  for (let k = 0; k < g.length; k++) {
+    const c = g[k];
+    if (c === '*') { if (g[k + 1] === '*') { s += '.*'; k++; if (g[k + 1] === '/') k++; } else s += '[^/]*'; }
+    else if (c === '?') s += '[^/]';
+    else s += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`);
+}
+export const matchAny = (globs, s) => (globs || []).some((g) => globToRe(g).test(s));
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg']);
+function walk(dir, base = dir, out = []) {
+  let ents; try { ents = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of ents) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, base, out);
+    else if (e.isFile()) out.push(relative(base, p).split(sep).join('/'));
+  }
+  return out;
+}
+
+/** URL path for a built file: index.html -> "/", a/index.html -> "/a/", a.html -> "/a.html" (or "/a" with cleanUrls). */
+export function pathForFile(file, { cleanUrls = false } = {}) {
+  if (/(^|\/)index\.html?$/i.test(file)) return '/' + file.replace(/index\.html?$/i, '');
+  return '/' + (cleanUrls ? file.replace(/\.html?$/i, '') : file);
+}
+export function normPath(p) {
+  let s = String(p || '/').split('#')[0].split('?')[0];
+  try { s = decodeURI(s); } catch { /* keep */ }
+  if (!s.startsWith('/')) s = '/' + s;
+  return s.replace(/\/{2,}/g, '/');
+}
+
+/**
+ * Load a built static site. opts: { baseUrl, include, exclude, cleanUrls }.
+ * Returns { dir, files, pages, baseUrl, origin, find(urlOrPath), resolve(page, href), isInternal(url), headersFor(path), read(rel) }.
+ */
+export function loadSite(dir, opts = {}) {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw Object.assign(new Error(`No such directory: ${dir}`), { code: 'ENOENT' });
+  const files = walk(dir).sort();
+  const htmlFiles = files.filter((f) => /\.html?$/i.test(f) && !matchAny(opts.exclude, f) && !matchAny(opts.exclude, pathForFile(f, opts)) && (!opts.include?.length || matchAny(opts.include, f) || matchAny(opts.include, pathForFile(f, opts))));
+  const cache = new Map();
+  const pages = htmlFiles.map((file) => {
+    const page = { file, path: pathForFile(file, opts) };
+    Object.defineProperty(page, 'html', { get: () => readFileSync(join(dir, file), 'utf8') });
+    Object.defineProperty(page, 'doc', { get: () => { if (!cache.has(file)) cache.set(file, parseHtml(readFileSync(join(dir, file), 'utf8'))); return cache.get(file); }, enumerable: false });
+    return page;
+  });
+  const index = new Map();
+  const keyVariants = (path) => { const p = normPath(path).toLowerCase(); const out = [p]; if (p.endsWith('/')) { out.push(p + 'index.html', p + 'index.htm'); if (p !== '/') out.push(p.slice(0, -1)); } else if (/\.html?$/.test(p)) { out.push(p.replace(/\.html?$/, '')); if (/\/index\.html?$/.test(p)) out.push(p.replace(/index\.html?$/, '')); } else out.push(p + '/', p + '.html'); return out; };
+  for (const pg of pages) for (const k of keyVariants('/' + pg.file).concat(keyVariants(pg.path))) if (!index.has(k)) index.set(k, pg);
+
+  let baseUrl = opts.baseUrl ? String(opts.baseUrl).replace(/\/+$/, '') : null;
+  if (!baseUrl) {
+    const counts = new Map();
+    for (const pg of pages.slice(0, 60)) { const d = pg.doc; for (const v of [d.links.find((l) => l.rel.includes('canonical'))?.href, d.metaContent('og:url')]) { try { const u = new URL(v); if (/^https?:$/.test(u.protocol)) counts.set(u.origin, (counts.get(u.origin) || 0) + 1); } catch { /* relative */ } } }
+    baseUrl = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  }
+  let origin = null; let basePath = '';
+  if (baseUrl) { try { const u = new URL(baseUrl); origin = u.origin; basePath = u.pathname.replace(/\/+$/, ''); } catch { throw Object.assign(new Error(`Invalid base URL: ${baseUrl}`), { code: 'EINVAL', usage: true }); } }
+  const site = { dir, files, pages, baseUrl, origin, basePath, inferredBase: !opts.baseUrl && !!baseUrl };
+  site.urlOf = (pg) => (origin ? origin + basePath + pg.path : pg.path);
+  /** Absolute URL object for href as seen from page (honours <base href>). */
+  site.resolve = (pg, href) => {
+    if (href == null) return null; href = String(href).trim();
+    if (!href || /^(javascript|mailto|tel|data|sms|ftp|blob):/i.test(href)) return null;
+    const pageUrl = (origin || 'http://site.invalid') + basePath + pg.path;
+    try { const b = pg.doc?.base ? new URL(pg.doc.base, pageUrl).href : pageUrl; return new URL(href, b); } catch { return null; }
+  };
+  site.isInternal = (u) => { if (!u) return false; const o = origin || 'http://site.invalid'; if (u.origin === o) return true; if (origin) { try { const a = new URL(o); return u.hostname.replace(/^www\./, '') === a.hostname.replace(/^www\./, '') && false; } catch { return false; } } return false; };
+  /** Find the page for a URL / path / URL object. Returns undefined for external or unknown. */
+  site.find = (x) => {
+    let path;
+    if (x instanceof URL) { if (!(x.origin === (origin || 'http://site.invalid'))) return undefined; path = x.pathname; }
+    else { const s = String(x); if (/^[a-z][a-z0-9+.-]*:/i.test(s)) { try { const u = new URL(s); if (u.origin !== (origin || 'http://site.invalid')) return undefined; path = u.pathname; } catch { return undefined; } } else path = s; }
+    if (basePath && path.startsWith(basePath)) path = path.slice(basePath.length) || '/';
+    for (const k of keyVariants(path)) { const pg = index.get(k); if (pg) return pg; }
+    return undefined;
+  };
+  site.read = (rel) => { try { return readFileSync(join(dir, rel), 'utf8'); } catch { return null; } };
+  site.exists = (rel) => existsSync(join(dir, rel));
+  const rules = loadHeaderRules(dir);
+  site.headerRules = rules;
+  site.headersFor = (path) => { const out = {}; for (const r of rules) if (r.re.test(path) || r.re.test(path.replace(/\/$/, '')) ) for (const [k, v] of r.headers) (out[k] ||= []).push({ value: v, source: r.source, line: r.line }); return out; };
+  return site;
+}
+
+/** Header rules from Netlify / Cloudflare Pages `_headers` and `vercel.json`. */
+export function loadHeaderRules(dir) {
+  const rules = [];
+  const hf = join(dir, '_headers');
+  if (existsSync(hf)) {
+    let cur = null;
+    readFileSync(hf, 'utf8').split(/\r?\n/).forEach((l, i) => {
+      if (!l.trim() || l.trim().startsWith('#')) return;
+      if (!/^\s/.test(l)) { const pat = l.trim(); cur = { source: '_headers', line: i + 1, pattern: pat, re: pathPatternRe(pat), headers: [] }; rules.push(cur); }
+      else if (cur) { const m = /^\s+([^:]+):\s*(.*)$/.exec(l); if (m) cur.headers.push([m[1].trim().toLowerCase(), m[2].trim()]); }
+    });
+  }
+  for (const f of ['vercel.json', '../vercel.json']) {
+    const vf = join(dir, f); if (!existsSync(vf)) continue;
+    try { const j = JSON.parse(readFileSync(vf, 'utf8')); const text = readFileSync(vf, 'utf8').split('\n'); for (const h of j.headers || []) { const ln = text.findIndex((l) => l.includes(JSON.stringify(h.source))) + 1 || undefined; rules.push({ source: f.replace('../', ''), line: ln, pattern: h.source, re: pathPatternRe(h.source), headers: (h.headers || []).map((x) => [String(x.key).toLowerCase(), String(x.value)]) }); } } catch { /* ignore */ }
+    break;
+  }
+  return rules;
+}
+function pathPatternRe(p) {
+  try { if (/^https?:\/\//.test(p)) p = new URL(p).pathname; } catch { /* keep */ }
+  if (/\(.*\)/.test(p) && !/:\w/.test(p.replace(/\(.*\)/g, ''))) { try { return new RegExp('^' + p.replace(/\//g, '\\/') + '$'); } catch { /* fall through */ } }
+  let s = '';
+  for (let k = 0; k < p.length; k++) {
+    const c = p[k];
+    if (c === '*') s += '.*';
+    else if (c === ':' && /\w/.test(p[k + 1] || '')) { const m = /^:(\w+)(\*|\+|\?)?(\([^)]*\))?/.exec(p.slice(k)); k += m[0].length - 1; s += m[2] === '*' || m[2] === '+' ? '.*' : m[3] ? m[3] : '[^/]+'; }
+    else s += c.replace(/[.+^${}()|[\]\\?]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`);
+}
+
+/** Robots directives that apply to a page from meta tags and X-Robots-Tag headers. bots: lowercased names. */
+export function robotsDirectives(site, pg, bots = ['robots', 'googlebot']) {
+  const out = [];
+  for (const m of pg.doc.robots(bots)) out.push({ bot: m.name, directives: m.directives, source: 'meta', file: pg.file, line: m.line, inHead: m.inHead, raw: m.content });
+  for (const h of site.headersFor(pg.path)['x-robots-tag'] || []) {
+    const v = h.value; const mm = /^([a-z0-9_-]+)\s*:\s*(.*)$/i.exec(v);
+    const bot = mm && !/^(noindex|nofollow|none|all|index|follow|noarchive|nosnippet|unavailable_after|max-snippet|max-image-preview|max-video-preview|noimageindex|notranslate|indexifembedded)$/i.test(mm[1]) ? mm[1].toLowerCase() : 'robots';
+    const body = bot === 'robots' ? v : mm[2];
+    if (bot === 'robots' || bots.includes(bot)) out.push({ bot, directives: body.toLowerCase().split(',').map((d) => d.trim()).filter(Boolean), source: 'header', file: h.source, line: h.line, raw: v });
+  }
+  return out;
+}
+export const isNoindex = (dirs) => dirs.some((d) => d.directives.some((x) => x === 'noindex' || x === 'none'));
+
+/** Page-level helpers shared across beacons. */
+export function canonicalOf(site, pg) {
+  const c = pg.doc.links.filter((l) => l.rel.includes('canonical') && l.href != null);
+  const hdr = (site.headersFor(pg.path).link || []).map((h) => /<([^>]+)>\s*;\s*rel="?canonical"?/i.exec(h.value)?.[1]).filter(Boolean);
+  const href = c.find((l) => l.inHead)?.href ?? c[0]?.href ?? hdr[0] ?? null;
+  return { href, url: href != null ? site.resolve(pg, href) : null, tags: c, header: hdr };
+}
+
+/** Very small JSON-LD helpers. */
+export function jsonldNodes(doc) {
+  const out = [];
+  const visit = (n, block, depth = 0) => {
+    if (Array.isArray(n)) { n.forEach((x) => visit(x, block, depth)); return; }
+    if (!n || typeof n !== 'object') return;
+    if (n['@graph']) visit(n['@graph'], block, depth);
+    if (n['@type']) out.push({ node: n, types: [].concat(n['@type']).map(String), line: block.line, depth });
+    for (const [k, v] of Object.entries(n)) if (k !== '@graph' && k !== '@context' && v && typeof v === 'object') visit(v, block, depth + 1);
+  };
+  for (const b of doc.jsonld) if (b.data) visit(b.data, b);
+  return out;
+}
+export const typeName = (t) => String(t).replace(/^https?:\/\/schema\.org\//, '').replace(/^schema:/, '');
+
+// ---------------------------------------------------------------------------------------------- CLI glue
+export const SITE_OPTIONS = { 'base-url': { type: 'string' }, include: { type: 'string', multiple: true }, exclude: { type: 'string', multiple: true }, 'clean-urls': { type: 'boolean' } };
+export const SITE_HELP = `Site
+      --base-url <url>        Public URL of the site, e.g. https://example.com (default: inferred from canonical/og:url)
+      --include <globs>       Only check these pages (file or URL path globs, comma-separated)
+      --exclude <globs>       Skip these pages
+      --clean-urls            Pages are served without .html (about.html -> /about)
+`;
+const list = (v) => (v || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+export function siteOptions(o = {}, config = {}) {
+  return { baseUrl: o['base-url'] ?? config.baseUrl, include: [...list(config.include), ...list(o.include)], exclude: [...list(config.exclude), ...list(o.exclude)], cleanUrls: o['clean-urls'] ?? config.cleanUrls ?? false };
+}
+/** Run a beacon: loads the site, calls analyze(site, opts) -> { findings, info, summary }, returns a report via buildReport. */
+export function runBeacon(tool, dir, opts, config, configFile, analyze, buildReport) {
+  let site;
+  try { site = loadSite(dir, siteOptions(opts.cli || {}, { ...config, ...pick(opts, ['baseUrl', 'include', 'exclude', 'cleanUrls']) })); }
+  catch (e) { if (e.usage || e.code === 'ENOENT') { const U = opts.UsageError || Error; throw new U(e.message); } throw e; }
+  const { findings, info = {}, summary } = analyze(site, opts, config);
+  const line = summary ?? `${site.pages.length} page(s)${site.baseUrl ? ` at ${site.baseUrl}${site.inferredBase ? ' (inferred)' : ''}` : ' (no base URL; pass --base-url)'}`;
+  return buildReport(tool, site.baseUrl || dir, findings, config, { now: opts.now, configFile, summaryLine: line, info: { pages: site.pages.length, baseUrl: site.baseUrl, ...info } });
+}
+function pick(o, keys) { const r = {}; for (const k of keys) if (o[k] !== undefined && !(Array.isArray(o[k]) && !o[k].length)) r[k] = o[k]; return r; }
+/** Finding factory bound to a rule table. */
+export function finder(RULES, findings = []) {
+  const add = (rule, subject, message, fix, loc = {}) => { if (!RULES[rule]) throw new Error(`unknown rule ${rule}`); findings.push({ rule, severity: loc.severity || RULES[rule].severity, subject, file: loc.file, line: loc.line, message, fix }); };
+  return { findings, add };
+}
+/** Redirect stubs (meta refresh) and error pages are skipped by most checks. */
+export const isRedirectStub = (pg) => pg.doc.metas.some((m) => m.httpEquiv === 'refresh');
+export const isErrorPage = (pg) => /(^|\/)(404|500|50x|error)(\/index)?\.html?$/i.test(pg.file);
+export const contentPages = (site) => site.pages.filter((p) => !isRedirectStub(p) && !isErrorPage(p));
+/** Published / modified dates a page declares (JSON-LD, Open Graph article tags, <time itemprop>, meta). Values are Date or null. */
+export function pageDates(doc) {
+  const pick = (vals) => { for (const v of vals) { if (!v) continue; const d = new Date(String(v).trim()); if (!Number.isNaN(d.getTime())) return d; } return null; };
+  const ld = jsonldNodes(doc).map((n) => n.node);
+  const ldv = (k) => ld.map((n) => [].concat(n[k] ?? [])[0]).filter(Boolean);
+  const timeProp = (k) => doc.all.filter((e) => e.attrs.itemprop === k).map((e) => e.attrs.datetime || e.attrs.content);
+  return {
+    published: pick([...ldv('datePublished'), doc.metaContent('article:published_time'), ...timeProp('datePublished'), doc.metaContent('date'), doc.metaContent('dc.date'), doc.metaContent('pubdate')]),
+    modified: pick([...ldv('dateModified'), doc.metaContent('article:modified_time'), doc.metaContent('og:updated_time'), ...timeProp('dateModified'), doc.metaContent('last-modified')]),
+  };
+}