lazy-pulse 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 (2026-10-14)
+
+First release, by Louis Wright.
+
+- LCP candidate detection (fetchpriority="high", preloaded image, else first content image; icons, nav and tracking pixels skipped).
+- LCP checks: `loading="lazy"`, JavaScript lazy-loading (`data-src`), `fetchpriority="low"`, preload/lazy conflicts.
+- Below-the-fold images and iframes without `loading="lazy"`, with a configurable fold (`foldImages`).
+- Lazy images without width/height; JS lazy-load libraries where native lazy loading would do.
+- 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,182 @@
-# Temporary Holding Version
+# lazy-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.
+> Lazy-load what is below the fold, never the LCP image: a static lazy-loading audit for your built site.
+
+Native `loading="lazy"` is one attribute, and it is easy to get wrong in both directions: galleries and embeds below the fold download eagerly, while a template applies `loading="lazy"` (or a `data-src` library) to the hero image and pushes back Largest Contentful Paint. `lazy-pulse` reads your built HTML, picks the likely LCP image on each page, and checks every image and iframe against where it sits in the document.
+
+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
+
+- **LCP candidate:** the image with `fetchpriority="high"`, else a preloaded image, else the first content image (icons, logos in nav/header, tracking pixels and `<noscript>` are skipped).
+- **LCP mistakes:** `loading="lazy"` (high), lazy-loaded by JavaScript via `data-src` (high), `fetchpriority="low"` (medium), a `<link rel=preload as=image>` for an image that is lazy (high), and no `fetchpriority` at all (info).
+- **Below the fold:** images and iframes without `loading="lazy"` after the first `foldImages` content images (default 1 after the LCP image); iframes (video, maps, widgets) are always expected to be lazy unless allowlisted.
+- **Above the fold:** content images near the top that are lazy (low).
+- **Hygiene:** lazy images without width/height or aspect-ratio (layout shift), and JS lazy-load libraries where native lazy loading would do.
+
+### Scope
+
+A static heuristic: there is no layout engine, so "the fold" is document order. Tune `foldImages` for your templates and allowlist the exceptions.
+
+## Rules
+
+| Rule | Default severity | What it means |
+|---|---|---|
+| `lazy-lcp-lazy` | high | LCP candidate image has loading="lazy" (delays the largest paint) |
+| `lazy-lcp-js` | high | LCP candidate is lazy-loaded by JavaScript (data-src, no real src) |
+| `lazy-preload-conflict` | high | Image is preloaded but its <img> has loading="lazy" |
+| `lazy-lcp-low-priority` | medium | LCP candidate has fetchpriority="low" |
+| `lazy-img-missing` | medium | Below-the-fold image without loading="lazy" |
+| `lazy-iframe-missing` | medium | Below-the-fold iframe without loading="lazy" |
+| `lazy-above-fold-lazy` | low | Image near the top of the page is lazy-loaded |
+| `lazy-no-dimensions` | low | Lazy-loaded image without width/height (layout shift when it loads) |
+| `lazy-js-library` | low | JavaScript lazy-loading (data-src) where native loading="lazy" would do |
+| `lazy-lcp-no-priority` | info | LCP candidate has no fetchpriority="high" |
+| `allowlist-expired` | medium | An allowlist entry is past its `expires` date |
+| `allowlist-unused` | info | An allowlist entry matched nothing |
+
+## Install and run
+
+```bash
+npx lazy-pulse dist
+npx lazy-pulse _site --fold-images 2
+npx lazy-pulse public --fail-on medium -f sarif > lazy.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
+lazy-pulse — test/fixtures/bad
+1 page(s), 7 image(s)/iframe(s), 4 lazy-loaded
+
+HIGH     index.html:6 LCP candidate hero.jpg on / has loading="lazy" [lazy-lcp-lazy]
+HIGH     index.html:6 /img/hero.jpg is preloaded on / but its <img> is loading="lazy" [lazy-preload-conflict]
+MEDIUM   index.html:9 Below-the-fold image a.jpg on / has no loading="lazy" [lazy-img-missing]
+MEDIUM   index.html:12 Below-the-fold image d.jpg on / has no loading="lazy" [lazy-img-missing]
+MEDIUM   index.html:13 iframe https://www.google.com/maps/embed?pb=1 on / is not lazy-loaded [lazy-iframe-missing]
+LOW      index.html:7 second.jpg is among the first 1 content images on / but has loading="lazy" [lazy-above-fold-lazy]
+LOW      index.html:10 Lazy image team.jpg on / has no width/height [lazy-no-dimensions]
+LOW      index.html:11 c.jpg on / is lazy-loaded with data-src [lazy-js-library]
+
+2 high, 3 medium, 3 low
+✔ Passing (fail-on: none).
+```
+
+## Options
+
+```text
+lazy-pulse 1.0.0 — lazy-loading audit: below-the-fold media without loading=lazy, LCP images wrongly lazy-loaded
+
+Usage: lazy-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)
+Lazy loading
+      --fold-images <n>        Content images treated as above the fold, after the LCP candidate (default 1)
+
+Common
+  -c, --config <file>     JSON config (default: .lazy-pulse.json or "lazyPulse" 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 `.lazy-pulse.json` (or a `"lazyPulse"` key in `package.json`, or `--config <file>`):
+
+```json
+{
+  "failOn": "medium",
+  "severity": {
+    "lazy-lcp-lazy": "low"
+  },
+  "allowlist": [
+    {
+      "rule": "lazy-iframe-missing",
+      "subject": "/contact/ *",
+      "reason": "Map is the main content of the contact page",
+      "expires": "2027-03-31"
+    }
+  ],
+  "foldImages": 2
+}
+```
+
+- **`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 `.lazy-pulse.json` can live at your repository root. Other keys: `foldImages` (content images after the LCP image treated as above the fold, default 1) and `iconSize` (images at or below this many px are icons, default 64).
+
+## 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:
+  lazy-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/lazy-pulse@v1
+        with:
+          path: dist
+          fail-on: high
+          sarif: lazy-pulse.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with: { sarif_file: lazy-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, parseHtml, mediaOf, lcpCandidate } from "lazy-pulse";
+const doc = parseHtml(html);
+lcpCandidate(doc, mediaOf(doc))?.el.attrs.src;
+check("dist", { foldImages: 2 }).findings;
+```
+
+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: 'lazy-pulse'
+description: 'Lazy-loading audit: below-the-fold media and wrongly lazy LCP images'
+author: 'Louis Wright'
+branding: { icon: 'image', 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/lazy-pulse.js
+      run: |
+        md="$RUNNER_TEMP/lazy-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/lazy-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: 'lazy-pulse', version: pkg.version, configKey: 'lazyPulse', rules: RULES,
+  tagline: 'lazy-loading audit: below-the-fold media without loading=lazy, LCP images wrongly lazy-loaded',
+  usage: 'Usage: lazy-pulse [site-dir] [options]',
+  help: `${SITE_HELP}Lazy loading
+      --fold-images <n>        Content images treated as above the fold, after the LCP candidate (default 1)
+`,
+  options: { ...SITE_OPTIONS, 'fold-images': { type: 'string' } },
+  run: async ({ dir, values: o, config, configFile }) => check(dir, { cli: o, foldImages: o['fold-images'], toolVersion: pkg.version }, config, configFile),
+});

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "lazy-pulse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Lazy-loading audit for static sites: below-the-fold images and iframes missing loading=lazy, and LCP candidates (hero images, first images) wrongly lazy-loaded or deprioritised. SARIF, 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": {
+    "lazy-pulse": "bin/lazy-pulse.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "action.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "lazy-loading",
+    "loading-lazy",
+    "lcp",
+    "performance",
+    "web-performance",
+    "core-web-vitals",
+    "images",
+    "static-site",
+    "sarif",
+    "github-action"
+  ],
+  "author": "Louis Wright <hello@louiswright.co.uk> (https://github.com/MrLouisWright)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrLouisWright/lazy-pulse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MrLouisWright/lazy-pulse/issues"
+  },
+  "homepage": "https://github.com/MrLouisWright/lazy-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,10 @@
+import type { Report, Rule } from './core.js';
+export * from './core.js';
+export interface LazyOptions { baseUrl?: string; include?: string[]; exclude?: string[]; cleanUrls?: boolean; foldImages?: number; toolVersion?: string; now?: Date }
+export interface Media { el: { tag: string; attrs: Record<string, string>; line: number }; kind: 'img' | 'iframe'; icon: boolean; chrome: boolean }
+export declare const RULES: Record<string, Rule>;
+export declare const DEFAULTS: { foldImages: number; iconSize: number };
+export declare function parseHtml(html: string): unknown;
+export declare function mediaOf(doc: unknown, opts?: { iconSize?: number }): Media[];
+export declare function lcpCandidate(doc: unknown, media: Media[]): Media | null;
+export declare function check(dir: string, opts?: LazyOptions, config?: Record<string, unknown>, configFile?: string): Report;

package/src/index.js

@@ -0,0 +1,92 @@
+// lazy-pulse: lazy-loading audit for a built static site. Finds below-the-fold images and iframes without
+// loading="lazy", and LCP candidates that are lazy-loaded, JS-lazy-loaded or deprioritised.
+// Static heuristic (document order, no layout engine). Zero dependencies. Louis Wright, MIT.
+import { runBeacon, finder, contentPages, ancestor } 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 = {
+  'lazy-lcp-lazy': { severity: 'high', title: 'LCP candidate image has loading="lazy" (delays the largest paint)' },
+  'lazy-lcp-js': { severity: 'high', title: 'LCP candidate is lazy-loaded by JavaScript (data-src, no real src)' },
+  'lazy-preload-conflict': { severity: 'high', title: 'Image is preloaded but its <img> has loading="lazy"' },
+  'lazy-lcp-low-priority': { severity: 'medium', title: 'LCP candidate has fetchpriority="low"' },
+  'lazy-img-missing': { severity: 'medium', title: 'Below-the-fold image without loading="lazy"' },
+  'lazy-iframe-missing': { severity: 'medium', title: 'Below-the-fold iframe without loading="lazy"' },
+  'lazy-above-fold-lazy': { severity: 'low', title: 'Image near the top of the page is lazy-loaded' },
+  'lazy-no-dimensions': { severity: 'low', title: 'Lazy-loaded image without width/height (layout shift when it loads)' },
+  'lazy-js-library': { severity: 'low', title: 'JavaScript lazy-loading (data-src) where native loading="lazy" would do' },
+  'lazy-lcp-no-priority': { severity: 'info', title: 'LCP candidate has no fetchpriority="high"' },
+};
+export const DEFAULTS = { foldImages: 1, iconSize: 64 };
+const JS_SRC = ['data-src', 'data-lazy-src', 'data-original', 'data-srcset'];
+const isLazy = (el) => String(el.attrs.loading || '').toLowerCase() === 'lazy';
+const jsLazy = (el) => JS_SRC.some((k) => el.attrs[k] != null) && (!el.attrs.src || /^data:|placeholder|blank|spacer|1x1/i.test(el.attrs.src));
+const num = (v) => { const n = parseInt(v, 10); return Number.isFinite(n) ? n : null; };
+const srcOf = (el) => (jsLazy(el) ? el.attrs['data-src'] || el.attrs['data-lazy-src'] || el.attrs['data-original'] : el.attrs.src) || el.attrs.src || '';
+const urlKey = (s) => String(s || '').split(/[?#]/)[0].replace(/^https?:\/\/[^/]+/, '').replace(/^\.?\/?/, '/');
+
+/** Media elements of a page in document order with classification: [{ el, kind, icon, chrome }]. */
+export function mediaOf(doc, opts = {}) {
+  const iconSize = opts.iconSize ?? DEFAULTS.iconSize; const out = [];
+  for (const el of doc.all) {
+    if (el.inHead || ancestor(el, (n) => n.tag === 'noscript' || n.tag === 'template')) continue;
+    if (el.tag === 'img') {
+      const w = num(el.attrs.width); const h = num(el.attrs.height); const src = srcOf(el);
+      const icon = (w != null && w <= iconSize && (h == null || h <= iconSize)) || (h != null && h <= iconSize && w == null) || /^data:/i.test(src) && !jsLazy(el) || el.attrs['aria-hidden'] === 'true' && w != null && w <= iconSize * 2;
+      const pixel = (w === 1 && h === 1) || /display\s*:\s*none/.test(el.attrs.style || '');
+      if (pixel) continue;
+      out.push({ el, kind: 'img', icon, chrome: !!ancestor(el, (n) => n.tag === 'nav' || n.tag === 'footer' || (n.tag === 'header' && !ancestor(n, (m) => m.tag === 'main' || m.tag === 'article'))) });
+    } else if (el.tag === 'iframe' && (el.attrs.src || el.attrs['data-src'])) out.push({ el, kind: 'iframe', icon: false, chrome: false });
+  }
+  return out;
+}
+
+/** The likely LCP image: fetchpriority=high, else a preloaded image, else the first non-icon content image. */
+export function lcpCandidate(doc, media) {
+  const imgs = media.filter((m) => m.kind === 'img');
+  const hi = imgs.find((m) => String(m.el.attrs.fetchpriority).toLowerCase() === 'high'); if (hi) return hi;
+  const pre = new Set(doc.all.filter((e) => e.tag === 'link' && /preload/i.test(e.attrs.rel || '') && e.attrs.as === 'image').map((e) => urlKey(e.attrs.href)));
+  const p = imgs.find((m) => pre.has(urlKey(srcOf(m.el)))); if (p) return p;
+  return imgs.find((m) => !m.icon && !m.chrome) || null;
+}
+
+function analyze(site, opts, config) {
+  const { findings, add } = finder(RULES);
+  const fold = opts.foldImages ?? config.foldImages ?? DEFAULTS.foldImages;
+  const pages = contentPages(site); let media = 0; let lazyCount = 0;
+  for (const pg of pages) {
+    const doc = pg.doc; const all = mediaOf(doc, config); media += all.length;
+    const lcp = lcpCandidate(doc, all);
+    const pre = doc.all.filter((e) => e.tag === 'link' && /preload/i.test(e.attrs.rel || '') && e.attrs.as === 'image');
+    const loc = (el) => ({ file: pg.file, line: el.line });
+    let contentIdx = 0;
+    for (const m of all) {
+      const { el } = m; const src = srcOf(el) || el.attrs.src || ''; const name = src.split('/').pop()?.split(/[?#]/)[0] || el.tag;
+      if (isLazy(el) || jsLazy(el)) lazyCount++;
+      if (m === lcp) {
+        if (isLazy(el)) add('lazy-lcp-lazy', `${pg.path} ${name}`, `LCP candidate ${name} on ${pg.path} has loading="lazy"`, 'Remove loading="lazy" from the hero/first content image and add fetchpriority="high".', loc(el));
+        else if (jsLazy(el)) add('lazy-lcp-js', `${pg.path} ${name}`, `LCP candidate ${name} on ${pg.path} is lazy-loaded by JavaScript (${JS_SRC.find((k) => el.attrs[k] != null)})`, 'Give the hero image a real src (and fetchpriority="high"); exclude it from the lazy-load library.', loc(el));
+        if (String(el.attrs.fetchpriority).toLowerCase() === 'low') add('lazy-lcp-low-priority', `${pg.path} ${name}`, `LCP candidate ${name} on ${pg.path} has fetchpriority="low"`, 'Use fetchpriority="high" on the LCP image.', loc(el));
+        else if (!el.attrs.fetchpriority && !isLazy(el) && !jsLazy(el)) add('lazy-lcp-no-priority', `${pg.path} ${name}`, `LCP candidate ${name} on ${pg.path} has no fetchpriority`, 'Add fetchpriority="high" to the hero image.', loc(el));
+        continue;
+      }
+      const above = m.kind === 'img' ? (!m.icon && !m.chrome ? contentIdx++ < fold : !!(m.chrome && ancestor(el, (n) => n.tag === 'header'))) : false;
+      if (m.kind === 'iframe') { if (!isLazy(el) && !jsLazy(el)) add('lazy-iframe-missing', `${pg.path} ${name}`, `iframe ${el.attrs.src || name} on ${pg.path} is not lazy-loaded`, 'Add loading="lazy" to embeds (video, maps, widgets) or use a click-to-load facade.', loc(el)); continue; }
+      if (m.icon) continue;
+      if (above) { if (isLazy(el) && !m.chrome) add('lazy-above-fold-lazy', `${pg.path} ${name}`, `${name} is among the first ${fold} content images on ${pg.path} but has loading="lazy"`, 'Load images near the top eagerly; lazy-load from the fold down. Adjust foldImages if your layout differs.', loc(el)); continue; }
+      if (!isLazy(el) && !jsLazy(el)) { if (!m.chrome || ancestor(el, (n) => n.tag === 'footer')) add('lazy-img-missing', `${pg.path} ${name}`, `Below-the-fold image ${name} on ${pg.path} has no loading="lazy"`, 'Add loading="lazy" (and decoding="async") to images below the fold.', loc(el)); continue; }
+      if (jsLazy(el)) add('lazy-js-library', `${pg.path} ${name}`, `${name} on ${pg.path} is lazy-loaded with ${JS_SRC.find((k) => el.attrs[k] != null)}`, 'Use native loading="lazy" with a real src; it needs no JavaScript and works before scripts run.', loc(el));
+      if (isLazy(el) && (el.attrs.width == null || el.attrs.height == null) && !/aspect-ratio/.test(el.attrs.style || '')) add('lazy-no-dimensions', `${pg.path} ${name}`, `Lazy image ${name} on ${pg.path} has no width/height`, 'Set width and height (or CSS aspect-ratio) so the space is reserved before it loads.', loc(el));
+    }
+    for (const l of pre) { const k = urlKey(l.attrs.href); const m = all.find((x) => x.kind === 'img' && urlKey(srcOf(x.el)) === k && isLazy(x.el)); if (m) add('lazy-preload-conflict', `${pg.path} ${k}`, `${k} is preloaded on ${pg.path} but its <img> is loading="lazy"`, 'Drop loading="lazy" from the image (or drop the preload).', { file: pg.file, line: m.el.line }); }
+  }
+  return { findings, info: { media, lazy: lazyCount }, summary: `${pages.length} page(s), ${media} image(s)/iframe(s), ${lazyCount} lazy-loaded` };
+}
+
+export function check(dir, opts = {}, config = {}, configFile) {
+  const tool = { name: 'lazy-pulse', version: opts.toolVersion || '1.0.0', rules: RULES, emoji: '💤', defaultFile: 'index.html' };
+  const f = opts.foldImages ?? config.foldImages; if (f != null && !(Number.isInteger(Number(f)) && Number(f) >= 0)) throw new UsageError('foldImages must be a non-negative integer');
+  return runBeacon(tool, dir, { ...opts, foldImages: f == null ? undefined : Number(f), 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')]),
+  };
+}