pagetrace 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 While the version is below 1.0.0, breaking changes ship in a minor release.
 
+## [0.13.0] - 2026-09-08
+
+### Added
+
+- `pagetrace page <url>` checks a single page: every link on it confirmed with a
+  real request, external ones included by default, plus that page's own rules.
+  A crawl trusts its route set and only verifies what is missing from it; with
+  one page there is no route set to trust, so everything is checked. Passing a
+  deep URL to `--url` had crawled the whole site from its origin and ignored the
+  path, which is not what it looked like it did.
+
+## [0.12.0] - 2026-09-08
+
+### Added
+
+- `--external` checks links that leave the site, on `links`, `audit`, `check`
+  and `snapshot`. Only 404 and 410 count as dead: a 403 from a bot wall, a 429,
+  a timeout and a TLS failure all describe the request rather than the page.
+  `HEAD` first with a `GET` fallback, one request per unique URL across the
+  site, capped at 200. Off by default — it fans out to hosts you do not control,
+  and recording their availability in a lockfile turns a third party's bad
+  afternoon into a diff in your repository.
+- `link.external.dead` (warn) and `link.external.dead.added`. A warning rather
+  than an error: the page belongs to someone who can delete it without asking.
+
+### Fixed
+
+- Absolute internal links were invisible. `extractLinks` dropped every href with
+  a scheme, so a site writing `https://example.com/about` rather than `/about`
+  had its links checked not at all. They are now resolved against the site's own
+  origin like any other link.
+
 ## [0.11.0] - 2026-09-08
 
 ### Added
@@ -338,6 +370,8 @@ Initial release. `snapshot`, `check` and `audit` commands; filesystem and HTTP
 crawling; diff classified by transition; absolute, cross-page and hreflang audit
 rules; pretty, JSON, markdown, GitHub and HTML reporters.
 
+[0.13.0]: https://github.com/shyamexe/pagetrace/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/shyamexe/pagetrace/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/shyamexe/pagetrace/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/shyamexe/pagetrace/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/shyamexe/pagetrace/compare/v0.9.0...v0.9.1

package/README.md

@@ -160,11 +160,20 @@ pagetrace update              # install it globally
 | `redirect.changed` | warn | A route redirects somewhere new |
 | `canonical.redirects` | warn | A canonical points at a URL that redirects |
 | `link.broken.added` | error | A page started linking to a URL that does not exist |
+| `link.external.dead` | warn | An outbound link answers 404 (needs `--external`) |
 | `sitemap.dead` | error | The sitemap lists a URL that answers 404 |
 | `sitemap.redirect` | warn | The sitemap lists a URL that redirects |
 | `og.removed` / `hreflang.removed` | warn | Social or i18n tags dropped |
 | `title.changed` | info | Ordinary copy edit |
 
+One page, checked on its own:
+
+```bash
+npx pagetrace page https://example.com/blog/my-post
+```
+
+No sitemap, no crawl: it fetches that URL and confirms every link on it with a real request, external links included by default (`--no-external` to skip them). Site-wide rules are left to `audit` — a single-page check never looks at robots.txt, so it does not get to say whether one exists.
+
 Broken links have a command of their own, when that is the only question you have:
 
 ```bash
@@ -174,7 +183,17 @@ npx pagetrace links --dir ./out --format json
 
 It crawls once, runs the same rules as `audit`, and prints only the link findings — exit 1 if any, or `No broken links found — 42 pages checked.`
 
-Internal links are checked too. Only the broken ones are stored, so a site's navigation never lands in the lockfile: `link.broken` for a link that is already dead, `link.broken.added` for one this build broke. A `--dir` crawl is authoritative — the build directory is the whole site — while a crawl confirms each candidate with a real request first, because a sitemap routinely omits pages that are live. External links are deliberately not checked: a Cloudflare 403 and a rate limit both look like a dead page, and that is where link checkers earn their reputation for false positives.
+Internal links are checked always. Outbound links are checked on request:
+
+```bash
+npx pagetrace links --url https://example.com --external
+```
+
+Only `404` and `410` count as dead. A `403` from a bot wall, a `429`, a timeout or a TLS failure are all reported as nothing at all, because they describe the request rather than the page — which is how link checkers turn into noise nobody reads. `HEAD` first, falling back to `GET` for servers that refuse it, one request per unique URL across the whole site, capped at 200.
+
+Think twice before putting `--external` in `check`. A third party's bad afternoon becomes a diff in your repository and a red build you cannot fix.
+
+Internal links are checked too. Only the broken ones are stored, so a site's navigation never lands in the lockfile: `link.broken` for a link that is already dead, `link.broken.added` for one this build broke. A `--dir` crawl is authoritative — the build directory is the whole site — while a crawl confirms each candidate with a real request first, because a sitemap routinely omits pages that are live. External links are checked only with `--external`, and only a 404 or 410 counts.
 
 Redirects are recorded from the response itself, so they cost no extra requests. A redirect that only adds or drops a trailing slash is server configuration rather than drift and is not reported. `canonical.redirects` is only raised when the canonical's target was actually crawled, so a `--limit` run cannot invent it.
 

package/dist/cli.cjs

@@ -254,13 +254,24 @@ function auditPage(page, config = {}) {
   return findings;
 }
 function auditLinks(page) {
-  return (page.brokenLinks ?? []).map((target) => ({
-    code: "link.broken",
-    severity: "error",
-    route: page.route,
-    message: `Links to ${target}, which does not exist.`,
-    after: target
-  }));
+  return [
+    ...(page.brokenLinks ?? []).map((target) => ({
+      code: "link.broken",
+      severity: "error",
+      route: page.route,
+      message: `Links to ${target}, which does not exist.`,
+      after: target
+    })),
+    // A warning, not an error: the page it points at belongs to somebody else,
+    // who can delete it on a Tuesday without asking you.
+    ...(page.deadExternal ?? []).map((target) => ({
+      code: "link.external.dead",
+      severity: "warn",
+      route: page.route,
+      message: `Links out to ${target}, which answers 404.`,
+      after: target
+    }))
+  ];
 }
 function auditSite(snapshot) {
   const findings = [];
@@ -631,6 +642,12 @@ function diffPage(before, after) {
     push("link.broken.removed", "info", `Link to ${target} was fixed or removed.`, {
       before: target
     });
+  const deadBefore = before.deadExternal ?? [];
+  const deadAfter = after.deadExternal ?? [];
+  for (const target of deadAfter.filter((t) => !deadBefore.includes(t)))
+    push("link.external.dead.added", "warn", `Links out to ${target}, which answers 404.`, {
+      after: target
+    });
   const droppedHreflang = Object.keys(before.hreflang).filter((k) => !(k in after.hreflang));
   if (droppedHreflang.length > 0)
     push("hreflang.removed", "warn", "hreflang alternates were removed.", {
@@ -739,6 +756,10 @@ var GUIDANCE = {
       nextjs: "A `<Link href>` pointing at a route that no longer exists. TypeScript will not catch it \u2014 typed routes are opt-in via `experimental.typedRoutes`."
     }
   },
+  "link.external.dead": {
+    why: "An outbound link to a page that is gone sends readers to a 404 and spends the trust the link was passing on nothing. Unlike an internal link, the page is not yours to restore.",
+    fix: "Point the link at the current URL, at an archived copy, or remove it. A link that has been dead a while is usually a citation worth replacing rather than deleting."
+  },
   "sitemap.dead": {
     why: "A sitemap is a list of URLs you are asking to have crawled. Entries that 404 spend crawl budget on nothing and lower the trust placed in the rest of the file.",
     fix: "Remove the URL from the sitemap, or restore the page. If it moved, redirect it and list the destination instead.",
@@ -1520,8 +1541,8 @@ function extractLinks(html) {
   const hrefs = /* @__PURE__ */ new Set();
   for (const anchor of root.querySelectorAll("a[href]")) {
     const href = anchor.getAttribute("href")?.trim();
-    if (!href) continue;
-    if (href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue;
+    if (!href || href.startsWith("#")) continue;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !/^https?:/i.test(href)) continue;
     hrefs.add(href);
   }
   return [...hrefs];
@@ -1615,6 +1636,7 @@ async function walkHtml(dir, acc = []) {
   }
   return acc;
 }
+var USER_AGENT = "pagetrace (+https://npmjs.com/package/pagetrace)";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var MAX_ATTEMPTS = 3;
 var RETRY_BASE_MS = 300;
@@ -1630,7 +1652,7 @@ async function fetchDoc(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
     try {
       response = await fetch(url, {
         signal: AbortSignal.timeout(timeoutMs),
-        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+        headers: { "user-agent": USER_AGENT }
       });
     } catch (cause) {
       lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
@@ -1675,7 +1697,9 @@ async function snapshotFromDir(dir, config = {}) {
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
   const llms = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
-  await resolveBrokenLinks(pages, links, site.origin ?? "https://pagetrace.invalid");
+  const origin = site.origin ?? "https://pagetrace.invalid";
+  await resolveBrokenLinks(pages, links, origin);
+  if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
@@ -1714,6 +1738,92 @@ async function resolveBrokenLinks(pages, links, origin, verify) {
     if (confirmed.length > 0) pages[route].brokenLinks = confirmed.sort();
   }
 }
+function externalUrl(href, from, origin) {
+  try {
+    const url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.origin === origin) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+var MAX_EXTERNAL_CHECKS = 200;
+async function findDeadExternal(urls, concurrency, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const dead = /* @__PURE__ */ new Set();
+  const queue = urls.slice(0, MAX_EXTERNAL_CHECKS);
+  const request = (url, method) => fetch(url, {
+    method,
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": USER_AGENT }
+  });
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        try {
+          let response = await request(url, "HEAD");
+          if (response.status === 405 || response.status === 501) {
+            response = await request(url, "GET");
+          }
+          if (response.status === 404 || response.status === 410) dead.add(url);
+        } catch {
+        }
+      }
+    })
+  );
+  return dead;
+}
+async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs) {
+  const perPage = /* @__PURE__ */ new Map();
+  const unique = /* @__PURE__ */ new Set();
+  for (const [route, hrefs] of Object.entries(links)) {
+    const external = [
+      ...new Set(
+        hrefs.map((href) => externalUrl(href, route, origin)).filter((url) => url !== null)
+      )
+    ];
+    if (external.length === 0) continue;
+    perPage.set(route, external);
+    for (const url of external) unique.add(url);
+  }
+  const dead = await findDeadExternal([...unique], concurrency, timeoutMs);
+  for (const [route, external] of perPage) {
+    const found = external.filter((url) => dead.has(url)).sort();
+    if (found.length > 0) pages[route].deadExternal = found;
+  }
+}
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, async (candidate) => {
+    try {
+      return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+    } catch {
+      return false;
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1802,6 +1912,9 @@ async function snapshotFromOrigin(origin, options = {}) {
       return false;
     }
   });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, base.origin, concurrency, timeout);
+  }
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 
@@ -1854,13 +1967,15 @@ async function loadConfig(path = DEFAULT_CONFIG) {
   }
 }
 async function build(flags, config) {
-  if (flags.dir) return snapshotFromDir(flags.dir, config);
+  const checkExternal = flags.external ?? config.checkExternal;
+  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal });
   if (flags.url)
     return snapshotFromOrigin(flags.url, {
       ...config,
       limit: flags.limit,
       concurrency: flags.concurrency,
-      ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots
+      ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots,
+      checkExternal
     });
   throw new Error("Provide a source: --dir <build directory> or --url <origin>.");
 }
@@ -1879,7 +1994,7 @@ function render(findings, format) {
   }
 }
 var cli = (0, import_cac.cac)("pagetrace");
-cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
   const written = await writeLockfile(flags.out, snapshot);
@@ -1888,7 +2003,7 @@ cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").opti
     written ? import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`) : import_picocolors2.default.dim(`${flags.out} is already up to date \u2014 ${count} page${count === 1 ? "" : "s"}.`)
   );
 });
-cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
+cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
   const config = await loadConfig(flags.config);
   const next = await build(flags, config);
@@ -1918,7 +2033,7 @@ Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
+cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -1958,7 +2073,43 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
+cli.command("page <url>", "Check one page: every link on it, and its own surface").option("--external", "Check links that leave the site", { default: true }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (url, flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await snapshotFromPage(url, {
+    ...config,
+    concurrency: flags.concurrency,
+    checkExternal: flags.external
+  });
+  const [page] = Object.values(snapshot.pages);
+  const platform = detectPlatform([page.generator], Object.values(page.og));
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.route !== null).map((f) => withGuidance(f, platform));
+  if (findings.length === 0 && !flags.out) {
+    const checked = (page.brokenLinks?.length ?? 0) + (page.deadExternal?.length ?? 0);
+    console.log(import_picocolors2.default.green(`${url} looks sound \u2014 no findings, no dead links.`));
+    if (checked > 0) console.log(import_picocolors2.default.dim("(unreachable links were treated as unknown, not dead)"));
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target: url,
+    platform,
+    pageCount: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : formatAuditPretty(groups, meta, process.stdout.columns);
+  if (flags.out) {
+    await (0, import_promises2.writeFile)(flags.out, `${output}
+`, "utf8");
+    console.log(import_picocolors2.default.green(`Wrote ${flags.out}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    process.exitCode = EXIT_FINDINGS;
+  }
+});
+cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -2005,7 +2156,7 @@ cli.command("links", "Find internal links that point at no page").option("--url
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("init", "Write a config file and take the first snapshot").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("init", "Write a config file and take the first snapshot").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const existing = await (0, import_promises2.readFile)(flags.config, "utf8").catch(() => null);
   if (existing === null) {
     const config = flags.url ? { siteUrl: new URL(flags.url).origin } : {};
@@ -2028,11 +2179,11 @@ Commit both files, then run \`pagetrace check ${flags.dir ? `--dir ${flags.dir}`
 });
 cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
   const latest = await latestVersion("pagetrace");
-  if (!isNewer(latest, "0.11.0")) {
-    console.log(import_picocolors2.default.green(`pagetrace ${"0.11.0"} is the latest version.`));
+  if (!isNewer(latest, "0.13.0")) {
+    console.log(import_picocolors2.default.green(`pagetrace ${"0.13.0"} is the latest version.`));
     return;
   }
-  console.log(import_picocolors2.default.yellow(`Update available: ${"0.11.0"} \u2192 ${latest}`));
+  console.log(import_picocolors2.default.yellow(`Update available: ${"0.13.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -2050,7 +2201,7 @@ cli.command("update", "Check npm for a newer pagetrace and install it").option("
   console.log(import_picocolors2.default.green(`Updated to pagetrace ${latest}.`));
 });
 cli.help();
-cli.version("0.11.0");
+cli.version("0.13.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/cli.js

@@ -231,13 +231,24 @@ function auditPage(page, config = {}) {
   return findings;
 }
 function auditLinks(page) {
-  return (page.brokenLinks ?? []).map((target) => ({
-    code: "link.broken",
-    severity: "error",
-    route: page.route,
-    message: `Links to ${target}, which does not exist.`,
-    after: target
-  }));
+  return [
+    ...(page.brokenLinks ?? []).map((target) => ({
+      code: "link.broken",
+      severity: "error",
+      route: page.route,
+      message: `Links to ${target}, which does not exist.`,
+      after: target
+    })),
+    // A warning, not an error: the page it points at belongs to somebody else,
+    // who can delete it on a Tuesday without asking you.
+    ...(page.deadExternal ?? []).map((target) => ({
+      code: "link.external.dead",
+      severity: "warn",
+      route: page.route,
+      message: `Links out to ${target}, which answers 404.`,
+      after: target
+    }))
+  ];
 }
 function auditSite(snapshot) {
   const findings = [];
@@ -608,6 +619,12 @@ function diffPage(before, after) {
     push("link.broken.removed", "info", `Link to ${target} was fixed or removed.`, {
       before: target
     });
+  const deadBefore = before.deadExternal ?? [];
+  const deadAfter = after.deadExternal ?? [];
+  for (const target of deadAfter.filter((t) => !deadBefore.includes(t)))
+    push("link.external.dead.added", "warn", `Links out to ${target}, which answers 404.`, {
+      after: target
+    });
   const droppedHreflang = Object.keys(before.hreflang).filter((k) => !(k in after.hreflang));
   if (droppedHreflang.length > 0)
     push("hreflang.removed", "warn", "hreflang alternates were removed.", {
@@ -716,6 +733,10 @@ var GUIDANCE = {
       nextjs: "A `<Link href>` pointing at a route that no longer exists. TypeScript will not catch it \u2014 typed routes are opt-in via `experimental.typedRoutes`."
     }
   },
+  "link.external.dead": {
+    why: "An outbound link to a page that is gone sends readers to a 404 and spends the trust the link was passing on nothing. Unlike an internal link, the page is not yours to restore.",
+    fix: "Point the link at the current URL, at an archived copy, or remove it. A link that has been dead a while is usually a citation worth replacing rather than deleting."
+  },
   "sitemap.dead": {
     why: "A sitemap is a list of URLs you are asking to have crawled. Entries that 404 spend crawl budget on nothing and lower the trust placed in the rest of the file.",
     fix: "Remove the URL from the sitemap, or restore the page. If it moved, redirect it and list the destination instead.",
@@ -1497,8 +1518,8 @@ function extractLinks(html) {
   const hrefs = /* @__PURE__ */ new Set();
   for (const anchor of root.querySelectorAll("a[href]")) {
     const href = anchor.getAttribute("href")?.trim();
-    if (!href) continue;
-    if (href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue;
+    if (!href || href.startsWith("#")) continue;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !/^https?:/i.test(href)) continue;
     hrefs.add(href);
   }
   return [...hrefs];
@@ -1592,6 +1613,7 @@ async function walkHtml(dir, acc = []) {
   }
   return acc;
 }
+var USER_AGENT = "pagetrace (+https://npmjs.com/package/pagetrace)";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var MAX_ATTEMPTS = 3;
 var RETRY_BASE_MS = 300;
@@ -1607,7 +1629,7 @@ async function fetchDoc(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
     try {
       response = await fetch(url, {
         signal: AbortSignal.timeout(timeoutMs),
-        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+        headers: { "user-agent": USER_AGENT }
       });
     } catch (cause) {
       lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
@@ -1652,7 +1674,9 @@ async function snapshotFromDir(dir, config = {}) {
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
   const llms = await readFile(join(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
-  await resolveBrokenLinks(pages, links, site.origin ?? "https://pagetrace.invalid");
+  const origin = site.origin ?? "https://pagetrace.invalid";
+  await resolveBrokenLinks(pages, links, origin);
+  if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
@@ -1691,6 +1715,92 @@ async function resolveBrokenLinks(pages, links, origin, verify) {
     if (confirmed.length > 0) pages[route].brokenLinks = confirmed.sort();
   }
 }
+function externalUrl(href, from, origin) {
+  try {
+    const url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.origin === origin) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+var MAX_EXTERNAL_CHECKS = 200;
+async function findDeadExternal(urls, concurrency, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const dead = /* @__PURE__ */ new Set();
+  const queue = urls.slice(0, MAX_EXTERNAL_CHECKS);
+  const request = (url, method) => fetch(url, {
+    method,
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": USER_AGENT }
+  });
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        try {
+          let response = await request(url, "HEAD");
+          if (response.status === 405 || response.status === 501) {
+            response = await request(url, "GET");
+          }
+          if (response.status === 404 || response.status === 410) dead.add(url);
+        } catch {
+        }
+      }
+    })
+  );
+  return dead;
+}
+async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs) {
+  const perPage = /* @__PURE__ */ new Map();
+  const unique = /* @__PURE__ */ new Set();
+  for (const [route, hrefs] of Object.entries(links)) {
+    const external = [
+      ...new Set(
+        hrefs.map((href) => externalUrl(href, route, origin)).filter((url) => url !== null)
+      )
+    ];
+    if (external.length === 0) continue;
+    perPage.set(route, external);
+    for (const url of external) unique.add(url);
+  }
+  const dead = await findDeadExternal([...unique], concurrency, timeoutMs);
+  for (const [route, external] of perPage) {
+    const found = external.filter((url) => dead.has(url)).sort();
+    if (found.length > 0) pages[route].deadExternal = found;
+  }
+}
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, async (candidate) => {
+    try {
+      return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+    } catch {
+      return false;
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1779,6 +1889,9 @@ async function snapshotFromOrigin(origin, options = {}) {
       return false;
     }
   });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, base.origin, concurrency, timeout);
+  }
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 
@@ -1831,13 +1944,15 @@ async function loadConfig(path = DEFAULT_CONFIG) {
   }
 }
 async function build(flags, config) {
-  if (flags.dir) return snapshotFromDir(flags.dir, config);
+  const checkExternal = flags.external ?? config.checkExternal;
+  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal });
   if (flags.url)
     return snapshotFromOrigin(flags.url, {
       ...config,
       limit: flags.limit,
       concurrency: flags.concurrency,
-      ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots
+      ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots,
+      checkExternal
     });
   throw new Error("Provide a source: --dir <build directory> or --url <origin>.");
 }
@@ -1856,7 +1971,7 @@ function render(findings, format) {
   }
 }
 var cli = cac("pagetrace");
-cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
   const written = await writeLockfile(flags.out, snapshot);
@@ -1865,7 +1980,7 @@ cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").opti
     written ? pc2.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`) : pc2.dim(`${flags.out} is already up to date \u2014 ${count} page${count === 1 ? "" : "s"}.`)
   );
 });
-cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
+cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
   const config = await loadConfig(flags.config);
   const next = await build(flags, config);
@@ -1895,7 +2010,7 @@ Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
+cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -1935,7 +2050,43 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
+cli.command("page <url>", "Check one page: every link on it, and its own surface").option("--external", "Check links that leave the site", { default: true }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (url, flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await snapshotFromPage(url, {
+    ...config,
+    concurrency: flags.concurrency,
+    checkExternal: flags.external
+  });
+  const [page] = Object.values(snapshot.pages);
+  const platform = detectPlatform([page.generator], Object.values(page.og));
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.route !== null).map((f) => withGuidance(f, platform));
+  if (findings.length === 0 && !flags.out) {
+    const checked = (page.brokenLinks?.length ?? 0) + (page.deadExternal?.length ?? 0);
+    console.log(pc2.green(`${url} looks sound \u2014 no findings, no dead links.`));
+    if (checked > 0) console.log(pc2.dim("(unreachable links were treated as unknown, not dead)"));
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target: url,
+    platform,
+    pageCount: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : formatAuditPretty(groups, meta, process.stdout.columns);
+  if (flags.out) {
+    await writeFile(flags.out, `${output}
+`, "utf8");
+    console.log(pc2.green(`Wrote ${flags.out}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    process.exitCode = EXIT_FINDINGS;
+  }
+});
+cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -1982,7 +2133,7 @@ cli.command("links", "Find internal links that point at no page").option("--url
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("init", "Write a config file and take the first snapshot").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("init", "Write a config file and take the first snapshot").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const existing = await readFile2(flags.config, "utf8").catch(() => null);
   if (existing === null) {
     const config = flags.url ? { siteUrl: new URL(flags.url).origin } : {};
@@ -2005,11 +2156,11 @@ Commit both files, then run \`pagetrace check ${flags.dir ? `--dir ${flags.dir}`
 });
 cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
   const latest = await latestVersion("pagetrace");
-  if (!isNewer(latest, "0.11.0")) {
-    console.log(pc2.green(`pagetrace ${"0.11.0"} is the latest version.`));
+  if (!isNewer(latest, "0.13.0")) {
+    console.log(pc2.green(`pagetrace ${"0.13.0"} is the latest version.`));
     return;
   }
-  console.log(pc2.yellow(`Update available: ${"0.11.0"} \u2192 ${latest}`));
+  console.log(pc2.yellow(`Update available: ${"0.13.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -2027,7 +2178,7 @@ cli.command("update", "Check npm for a newer pagetrace and install it").option("
   console.log(pc2.green(`Updated to pagetrace ${latest}.`));
 });
 cli.help();
-cli.version("0.11.0");
+cli.version("0.13.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/index.cjs

@@ -67,6 +67,7 @@ __export(src_exports, {
   snapshotFromDir: () => snapshotFromDir,
   snapshotFromGitRef: () => snapshotFromGitRef,
   snapshotFromOrigin: () => snapshotFromOrigin,
+  snapshotFromPage: () => snapshotFromPage,
   summarize: () => summarize,
   withGuidance: () => withGuidance
 });
@@ -297,13 +298,24 @@ function auditPage(page, config = {}) {
   return findings;
 }
 function auditLinks(page) {
-  return (page.brokenLinks ?? []).map((target) => ({
-    code: "link.broken",
-    severity: "error",
-    route: page.route,
-    message: `Links to ${target}, which does not exist.`,
-    after: target
-  }));
+  return [
+    ...(page.brokenLinks ?? []).map((target) => ({
+      code: "link.broken",
+      severity: "error",
+      route: page.route,
+      message: `Links to ${target}, which does not exist.`,
+      after: target
+    })),
+    // A warning, not an error: the page it points at belongs to somebody else,
+    // who can delete it on a Tuesday without asking you.
+    ...(page.deadExternal ?? []).map((target) => ({
+      code: "link.external.dead",
+      severity: "warn",
+      route: page.route,
+      message: `Links out to ${target}, which answers 404.`,
+      after: target
+    }))
+  ];
 }
 function auditSite(snapshot) {
   const findings = [];
@@ -674,6 +686,12 @@ function diffPage(before, after) {
     push("link.broken.removed", "info", `Link to ${target} was fixed or removed.`, {
       before: target
     });
+  const deadBefore = before.deadExternal ?? [];
+  const deadAfter = after.deadExternal ?? [];
+  for (const target of deadAfter.filter((t) => !deadBefore.includes(t)))
+    push("link.external.dead.added", "warn", `Links out to ${target}, which answers 404.`, {
+      after: target
+    });
   const droppedHreflang = Object.keys(before.hreflang).filter((k) => !(k in after.hreflang));
   if (droppedHreflang.length > 0)
     push("hreflang.removed", "warn", "hreflang alternates were removed.", {
@@ -962,8 +980,8 @@ function extractLinks(html) {
   const hrefs = /* @__PURE__ */ new Set();
   for (const anchor of root.querySelectorAll("a[href]")) {
     const href = anchor.getAttribute("href")?.trim();
-    if (!href) continue;
-    if (href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue;
+    if (!href || href.startsWith("#")) continue;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !/^https?:/i.test(href)) continue;
     hrefs.add(href);
   }
   return [...hrefs];
@@ -1021,6 +1039,10 @@ var GUIDANCE = {
       nextjs: "A `<Link href>` pointing at a route that no longer exists. TypeScript will not catch it \u2014 typed routes are opt-in via `experimental.typedRoutes`."
     }
   },
+  "link.external.dead": {
+    why: "An outbound link to a page that is gone sends readers to a 404 and spends the trust the link was passing on nothing. Unlike an internal link, the page is not yours to restore.",
+    fix: "Point the link at the current URL, at an archived copy, or remove it. A link that has been dead a while is usually a citation worth replacing rather than deleting."
+  },
   "sitemap.dead": {
     why: "A sitemap is a list of URLs you are asking to have crawled. Entries that 404 spend crawl budget on nothing and lower the trust placed in the rest of the file.",
     fix: "Remove the URL from the sitemap, or restore the page. If it moved, redirect it and list the destination instead.",
@@ -1656,6 +1678,7 @@ async function walkHtml(dir, acc = []) {
   }
   return acc;
 }
+var USER_AGENT = "pagetrace (+https://npmjs.com/package/pagetrace)";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var MAX_ATTEMPTS = 3;
 var RETRY_BASE_MS = 300;
@@ -1671,7 +1694,7 @@ async function fetchDoc(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
     try {
       response = await fetch(url, {
         signal: AbortSignal.timeout(timeoutMs),
-        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+        headers: { "user-agent": USER_AGENT }
       });
     } catch (cause) {
       lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
@@ -1716,7 +1739,9 @@ async function snapshotFromDir(dir, config = {}) {
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
   const llms = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
-  await resolveBrokenLinks(pages, links, site.origin ?? "https://pagetrace.invalid");
+  const origin = site.origin ?? "https://pagetrace.invalid";
+  await resolveBrokenLinks(pages, links, origin);
+  if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
@@ -1755,6 +1780,92 @@ async function resolveBrokenLinks(pages, links, origin, verify) {
     if (confirmed.length > 0) pages[route].brokenLinks = confirmed.sort();
   }
 }
+function externalUrl(href, from, origin) {
+  try {
+    const url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.origin === origin) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+var MAX_EXTERNAL_CHECKS = 200;
+async function findDeadExternal(urls, concurrency, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const dead = /* @__PURE__ */ new Set();
+  const queue = urls.slice(0, MAX_EXTERNAL_CHECKS);
+  const request = (url, method) => fetch(url, {
+    method,
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": USER_AGENT }
+  });
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        try {
+          let response = await request(url, "HEAD");
+          if (response.status === 405 || response.status === 501) {
+            response = await request(url, "GET");
+          }
+          if (response.status === 404 || response.status === 410) dead.add(url);
+        } catch {
+        }
+      }
+    })
+  );
+  return dead;
+}
+async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs) {
+  const perPage = /* @__PURE__ */ new Map();
+  const unique = /* @__PURE__ */ new Set();
+  for (const [route, hrefs] of Object.entries(links)) {
+    const external = [
+      ...new Set(
+        hrefs.map((href) => externalUrl(href, route, origin)).filter((url) => url !== null)
+      )
+    ];
+    if (external.length === 0) continue;
+    perPage.set(route, external);
+    for (const url of external) unique.add(url);
+  }
+  const dead = await findDeadExternal([...unique], concurrency, timeoutMs);
+  for (const [route, external] of perPage) {
+    const found = external.filter((url) => dead.has(url)).sort();
+    if (found.length > 0) pages[route].deadExternal = found;
+  }
+}
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, async (candidate) => {
+    try {
+      return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+    } catch {
+      return false;
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1843,6 +1954,9 @@ async function snapshotFromOrigin(origin, options = {}) {
       return false;
     }
   });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, base.origin, concurrency, timeout);
+  }
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1884,6 +1998,7 @@ async function snapshotFromOrigin(origin, options = {}) {
   snapshotFromDir,
   snapshotFromGitRef,
   snapshotFromOrigin,
+  snapshotFromPage,
   summarize,
   withGuidance
 });

package/dist/index.d.cts

@@ -50,6 +50,12 @@ interface PageFingerprint {
      * property the lockfile has to have.
      */
     brokenLinks?: string[];
+    /**
+     * External links that answered 404 or 410. Only present when the crawl was
+     * asked to check them: it means a request per unique external URL, to hosts
+     * you do not control.
+     */
+    deadExternal?: string[];
 }
 /** Site-wide signals that live outside any single page. */
 interface SiteFingerprint {
@@ -139,6 +145,12 @@ interface Config {
      * worse than crawling a site you already own.
      */
     ignoreRobots?: boolean;
+    /**
+     * Also check links that leave the site. Off by default: it fans out to hosts
+     * you do not control, and a lockfile that records their availability turns a
+     * third party's bad afternoon into a diff in your repository.
+     */
+    checkExternal?: boolean;
 }
 
 /**
@@ -186,12 +198,12 @@ declare function isCrawlable(path: string, rules: {
     allow?: string[];
 } | null | undefined): boolean;
 /**
- * Internal-looking hrefs on the page, deduplicated, in document order.
+ * Every href on the page worth resolving, deduplicated, in document order.
+ * Both internal and external: snapshot.ts is the only layer that knows the
+ * page's own URL, so classification happens there.
  *
- * Resolution happens in snapshot.ts, which is the only layer that knows the
- * page's own URL and the full set of routes. Anything with a scheme is somebody
- * else's problem: an external link checker fans out to hosts you do not
- * control, where a Cloudflare 403 and a rate limit both look like a dead page.
+ * Dropped here because they can never be dead: fragments, mailto:, tel:,
+ * javascript: and other non-http schemes.
  */
 declare function extractLinks(html: string): string[];
 /** Parse llms.txt, capturing section headings so truncation is detectable. */
@@ -305,6 +317,14 @@ declare function sameSurface(a: Snapshot, b: Snapshot): boolean;
 declare function shouldIgnore(route: string, patterns?: string[]): boolean;
 /** Build a snapshot from a directory of pre-rendered HTML (next export, dist, out). */
 declare function snapshotFromDir(dir: string, config?: Config): Promise<Snapshot>;
+/**
+ * One page, checked properly. No sitemap, no route discovery: the snapshot
+ * holds a single page, so every link on it is a candidate and every candidate
+ * is confirmed with a real request. That is the opposite trade from a crawl,
+ * and the right one here — one page's worth of links is a bounded cost, and
+ * "is this page's linking sound" is a question a crawl answers slowly.
+ */
+declare function snapshotFromPage(pageUrl: string, options?: CrawlOptions): Promise<Snapshot>;
 interface CrawlOptions extends Config {
     /** Cap the number of pages fetched. */
     limit?: number;
@@ -316,4 +336,4 @@ interface CrawlOptions extends Config {
 /** Build a snapshot by fetching a live origin, discovering routes via sitemap. */
 declare function snapshotFromOrigin(origin: string, options?: CrawlOptions): Promise<Snapshot>;
 
-export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, summarize, withGuidance };
+export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, snapshotFromPage, summarize, withGuidance };

package/dist/index.d.ts

@@ -50,6 +50,12 @@ interface PageFingerprint {
      * property the lockfile has to have.
      */
     brokenLinks?: string[];
+    /**
+     * External links that answered 404 or 410. Only present when the crawl was
+     * asked to check them: it means a request per unique external URL, to hosts
+     * you do not control.
+     */
+    deadExternal?: string[];
 }
 /** Site-wide signals that live outside any single page. */
 interface SiteFingerprint {
@@ -139,6 +145,12 @@ interface Config {
      * worse than crawling a site you already own.
      */
     ignoreRobots?: boolean;
+    /**
+     * Also check links that leave the site. Off by default: it fans out to hosts
+     * you do not control, and a lockfile that records their availability turns a
+     * third party's bad afternoon into a diff in your repository.
+     */
+    checkExternal?: boolean;
 }
 
 /**
@@ -186,12 +198,12 @@ declare function isCrawlable(path: string, rules: {
     allow?: string[];
 } | null | undefined): boolean;
 /**
- * Internal-looking hrefs on the page, deduplicated, in document order.
+ * Every href on the page worth resolving, deduplicated, in document order.
+ * Both internal and external: snapshot.ts is the only layer that knows the
+ * page's own URL, so classification happens there.
  *
- * Resolution happens in snapshot.ts, which is the only layer that knows the
- * page's own URL and the full set of routes. Anything with a scheme is somebody
- * else's problem: an external link checker fans out to hosts you do not
- * control, where a Cloudflare 403 and a rate limit both look like a dead page.
+ * Dropped here because they can never be dead: fragments, mailto:, tel:,
+ * javascript: and other non-http schemes.
  */
 declare function extractLinks(html: string): string[];
 /** Parse llms.txt, capturing section headings so truncation is detectable. */
@@ -305,6 +317,14 @@ declare function sameSurface(a: Snapshot, b: Snapshot): boolean;
 declare function shouldIgnore(route: string, patterns?: string[]): boolean;
 /** Build a snapshot from a directory of pre-rendered HTML (next export, dist, out). */
 declare function snapshotFromDir(dir: string, config?: Config): Promise<Snapshot>;
+/**
+ * One page, checked properly. No sitemap, no route discovery: the snapshot
+ * holds a single page, so every link on it is a candidate and every candidate
+ * is confirmed with a real request. That is the opposite trade from a crawl,
+ * and the right one here — one page's worth of links is a bounded cost, and
+ * "is this page's linking sound" is a question a crawl answers slowly.
+ */
+declare function snapshotFromPage(pageUrl: string, options?: CrawlOptions): Promise<Snapshot>;
 interface CrawlOptions extends Config {
     /** Cap the number of pages fetched. */
     limit?: number;
@@ -316,4 +336,4 @@ interface CrawlOptions extends Config {
 /** Build a snapshot by fetching a live origin, discovering routes via sitemap. */
 declare function snapshotFromOrigin(origin: string, options?: CrawlOptions): Promise<Snapshot>;
 
-export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, summarize, withGuidance };
+export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, snapshotFromPage, summarize, withGuidance };

package/dist/index.js

@@ -223,13 +223,24 @@ function auditPage(page, config = {}) {
   return findings;
 }
 function auditLinks(page) {
-  return (page.brokenLinks ?? []).map((target) => ({
-    code: "link.broken",
-    severity: "error",
-    route: page.route,
-    message: `Links to ${target}, which does not exist.`,
-    after: target
-  }));
+  return [
+    ...(page.brokenLinks ?? []).map((target) => ({
+      code: "link.broken",
+      severity: "error",
+      route: page.route,
+      message: `Links to ${target}, which does not exist.`,
+      after: target
+    })),
+    // A warning, not an error: the page it points at belongs to somebody else,
+    // who can delete it on a Tuesday without asking you.
+    ...(page.deadExternal ?? []).map((target) => ({
+      code: "link.external.dead",
+      severity: "warn",
+      route: page.route,
+      message: `Links out to ${target}, which answers 404.`,
+      after: target
+    }))
+  ];
 }
 function auditSite(snapshot) {
   const findings = [];
@@ -600,6 +611,12 @@ function diffPage(before, after) {
     push("link.broken.removed", "info", `Link to ${target} was fixed or removed.`, {
       before: target
     });
+  const deadBefore = before.deadExternal ?? [];
+  const deadAfter = after.deadExternal ?? [];
+  for (const target of deadAfter.filter((t) => !deadBefore.includes(t)))
+    push("link.external.dead.added", "warn", `Links out to ${target}, which answers 404.`, {
+      after: target
+    });
   const droppedHreflang = Object.keys(before.hreflang).filter((k) => !(k in after.hreflang));
   if (droppedHreflang.length > 0)
     push("hreflang.removed", "warn", "hreflang alternates were removed.", {
@@ -888,8 +905,8 @@ function extractLinks(html) {
   const hrefs = /* @__PURE__ */ new Set();
   for (const anchor of root.querySelectorAll("a[href]")) {
     const href = anchor.getAttribute("href")?.trim();
-    if (!href) continue;
-    if (href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue;
+    if (!href || href.startsWith("#")) continue;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !/^https?:/i.test(href)) continue;
     hrefs.add(href);
   }
   return [...hrefs];
@@ -947,6 +964,10 @@ var GUIDANCE = {
       nextjs: "A `<Link href>` pointing at a route that no longer exists. TypeScript will not catch it \u2014 typed routes are opt-in via `experimental.typedRoutes`."
     }
   },
+  "link.external.dead": {
+    why: "An outbound link to a page that is gone sends readers to a 404 and spends the trust the link was passing on nothing. Unlike an internal link, the page is not yours to restore.",
+    fix: "Point the link at the current URL, at an archived copy, or remove it. A link that has been dead a while is usually a citation worth replacing rather than deleting."
+  },
   "sitemap.dead": {
     why: "A sitemap is a list of URLs you are asking to have crawled. Entries that 404 spend crawl budget on nothing and lower the trust placed in the rest of the file.",
     fix: "Remove the URL from the sitemap, or restore the page. If it moved, redirect it and list the destination instead.",
@@ -1582,6 +1603,7 @@ async function walkHtml(dir, acc = []) {
   }
   return acc;
 }
+var USER_AGENT = "pagetrace (+https://npmjs.com/package/pagetrace)";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var MAX_ATTEMPTS = 3;
 var RETRY_BASE_MS = 300;
@@ -1597,7 +1619,7 @@ async function fetchDoc(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
     try {
       response = await fetch(url, {
         signal: AbortSignal.timeout(timeoutMs),
-        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+        headers: { "user-agent": USER_AGENT }
       });
     } catch (cause) {
       lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
@@ -1642,7 +1664,9 @@ async function snapshotFromDir(dir, config = {}) {
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
   const llms = await readFile(join(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
-  await resolveBrokenLinks(pages, links, site.origin ?? "https://pagetrace.invalid");
+  const origin = site.origin ?? "https://pagetrace.invalid";
+  await resolveBrokenLinks(pages, links, origin);
+  if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
@@ -1681,6 +1705,92 @@ async function resolveBrokenLinks(pages, links, origin, verify) {
     if (confirmed.length > 0) pages[route].brokenLinks = confirmed.sort();
   }
 }
+function externalUrl(href, from, origin) {
+  try {
+    const url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.origin === origin) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+var MAX_EXTERNAL_CHECKS = 200;
+async function findDeadExternal(urls, concurrency, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const dead = /* @__PURE__ */ new Set();
+  const queue = urls.slice(0, MAX_EXTERNAL_CHECKS);
+  const request = (url, method) => fetch(url, {
+    method,
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "user-agent": USER_AGENT }
+  });
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        try {
+          let response = await request(url, "HEAD");
+          if (response.status === 405 || response.status === 501) {
+            response = await request(url, "GET");
+          }
+          if (response.status === 404 || response.status === 410) dead.add(url);
+        } catch {
+        }
+      }
+    })
+  );
+  return dead;
+}
+async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs) {
+  const perPage = /* @__PURE__ */ new Map();
+  const unique = /* @__PURE__ */ new Set();
+  for (const [route, hrefs] of Object.entries(links)) {
+    const external = [
+      ...new Set(
+        hrefs.map((href) => externalUrl(href, route, origin)).filter((url) => url !== null)
+      )
+    ];
+    if (external.length === 0) continue;
+    perPage.set(route, external);
+    for (const url of external) unique.add(url);
+  }
+  const dead = await findDeadExternal([...unique], concurrency, timeoutMs);
+  for (const [route, external] of perPage) {
+    const found = external.filter((url) => dead.has(url)).sort();
+    if (found.length > 0) pages[route].deadExternal = found;
+  }
+}
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, async (candidate) => {
+    try {
+      return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+    } catch {
+      return false;
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1769,6 +1879,9 @@ async function snapshotFromOrigin(origin, options = {}) {
       return false;
     }
   });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, base.origin, concurrency, timeout);
+  }
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 export {
@@ -1809,6 +1922,7 @@ export {
   snapshotFromDir,
   snapshotFromGitRef,
   snapshotFromOrigin,
+  snapshotFromPage,
   summarize,
   withGuidance
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagetrace",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Baseline your site's SEO and AEO surface, diff every build against it, and fail CI on regressions.",
   "main": "./dist/index.cjs",
   "scripts": {