pagetrace 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ 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.4.0] - 2026-09-06
+
+### Changed
+
+- **Breaking.** A failed run now exits `2` rather than `1`. `1` means findings at
+  or above `--fail-on`; `2` means the run itself failed — invalid flags, an
+  unreadable build directory, an unreachable origin, no pages found. CI could not
+  previously distinguish "the site regressed" from "the tool broke", which are
+  opposite situations: one should fail the build, the other should page someone.
+- The lockfile is only rewritten when the surface actually changed. It carries a
+  `createdAt` timestamp, so every run used to produce a git diff even on an
+  unchanged site — which teaches reviewers to discard lockfile changes without
+  reading them, the one habit this tool cannot afford. `snapshot` and
+  `check --update` now say "already up to date" and leave the file alone.
+- Source maps are no longer published. They were 61% of the package: 715 kB
+  unpacked down to 281 kB. Nobody steps through a built CLI.
+- Build target moved from `node18` to `node20`, matching the engines floor.
+
+### Added
+
+- Failed requests are retried up to three times with backoff, on network errors,
+  429 and 5xx. 0.2.0 made an unreachable page abort the crawl rather than be
+  silently dropped, which is correct but brittle without a retry — one flaky
+  response could end a 200-page crawl. A 4xx is an answer, not a hiccup, and is
+  not retried.
+- `sameSurface(a, b)` is exported: compares two snapshots ignoring when they were
+  taken.
+- The release workflow creates a GitHub Release from each tag, using that
+  version's changelog section as the notes. A tag on its own does not appear in
+  the repo UI, so the project read as unreleased despite being on npm.
+
 ## [0.3.0] - 2026-09-06
 
 ### Changed
@@ -139,6 +170,7 @@ 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.4.0]: https://github.com/shyamexe/pagetrace/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/shyamexe/pagetrace/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/shyamexe/pagetrace/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/shyamexe/pagetrace/releases/tag/v0.1.0

package/README.md

@@ -48,10 +48,12 @@ npx pagetrace check --dir ./out
 5 error, 9 warning, 2 info
 ```
 
-Exit code is `1` when anything at or above `--fail-on` is found. It takes `error` (the default), `warn` or `info`, and rejects anything else rather than quietly letting the build pass.
+Exit codes are `0` for clean, `1` for findings at or above `--fail-on`, and `2` when the run itself failed — bad flags, an unreadable build directory, an unreachable origin. CI can tell "the site regressed" from "the tool broke". `--fail-on` takes `error` (the default), `warn` or `info`, and rejects anything else rather than quietly letting the build pass.
 
 Note that `check` runs the absolute rules as well as the diff, so it can fail on a problem your build did not introduce. Use `--no-audit` for a pure regression gate.
 
+The lockfile is only rewritten when the surface actually changed, so an unchanged site leaves it byte-identical and produces no git diff.
+
 Accept the new state once you've reviewed it:
 
 ```bash

package/dist/cli.cjs

@@ -1278,6 +1278,10 @@ function routeFromUrl(url) {
     return url;
   }
 }
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1296,19 +1300,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1405,6 +1422,15 @@ async function snapshotFromOrigin(origin, options = {}) {
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
+var EXIT_FINDINGS = 1;
+var EXIT_FAILURE = 2;
+async function writeLockfile(path, next) {
+  const previous = await (0, import_promises2.readFile)(path, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
+  if (previous && sameSurface(previous, next)) return false;
+  await (0, import_promises2.writeFile)(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return true;
+}
 var SEVERITIES = ["error", "warn", "info"];
 function parseFailOn(value, allowNever) {
   const expected = [...SEVERITIES, ...allowNever ? ["never"] : []].join(" | ");
@@ -1446,10 +1472,11 @@ 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("--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);
-  await (0, import_promises2.writeFile)(flags.out, `${JSON.stringify(snapshot, null, 2)}
-`, "utf8");
+  const written = await writeLockfile(flags.out, snapshot);
   const count = Object.keys(snapshot.pages).length;
-  console.log(import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`));
+  console.log(
+    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("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { 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").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
@@ -1473,9 +1500,10 @@ cli.command("check", "Compare the current surface against the lockfile").option(
   const findings = applyConfig(raw, config);
   console.log(render(findings, flags.format));
   if (flags.update) {
-    await (0, import_promises2.writeFile)(flags.lockfile, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    console.error(import_picocolors2.default.dim(`Updated ${flags.lockfile}.`));
+    const written = await writeLockfile(flags.lockfile, next);
+    console.error(
+      import_picocolors2.default.dim(written ? `Updated ${flags.lockfile}.` : `${flags.lockfile} is already up to date.`)
+    );
   }
   const summary = summarize(findings);
   if (previous && shouldFail(findings, failOn)) {
@@ -1483,7 +1511,7 @@ cli.command("check", "Compare the current surface against the lockfile").option(
       import_picocolors2.default.red(`
 Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`)
     );
-    process.exitCode = 1;
+    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("--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) => {
@@ -1497,7 +1525,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
         "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
       )
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
     return;
   }
   const platform = detectPlatform(
@@ -1523,19 +1551,18 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     console.log(output);
   }
   if (failOn !== "never" && shouldFail(findings, failOn)) {
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.help();
-cli.version("0.3.0");
+cli.version("0.4.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(import_picocolors2.default.red(error.message));
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
   }
 }
 void main();
-//# sourceMappingURL=cli.cjs.map

package/dist/cli.js

@@ -1255,6 +1255,10 @@ function routeFromUrl(url) {
     return url;
   }
 }
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1273,19 +1277,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1382,6 +1399,15 @@ async function snapshotFromOrigin(origin, options = {}) {
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
+var EXIT_FINDINGS = 1;
+var EXIT_FAILURE = 2;
+async function writeLockfile(path, next) {
+  const previous = await readFile2(path, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
+  if (previous && sameSurface(previous, next)) return false;
+  await writeFile(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return true;
+}
 var SEVERITIES = ["error", "warn", "info"];
 function parseFailOn(value, allowNever) {
   const expected = [...SEVERITIES, ...allowNever ? ["never"] : []].join(" | ");
@@ -1423,10 +1449,11 @@ 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("--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);
-  await writeFile(flags.out, `${JSON.stringify(snapshot, null, 2)}
-`, "utf8");
+  const written = await writeLockfile(flags.out, snapshot);
   const count = Object.keys(snapshot.pages).length;
-  console.log(pc2.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`));
+  console.log(
+    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("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { 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").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
@@ -1450,9 +1477,10 @@ cli.command("check", "Compare the current surface against the lockfile").option(
   const findings = applyConfig(raw, config);
   console.log(render(findings, flags.format));
   if (flags.update) {
-    await writeFile(flags.lockfile, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    console.error(pc2.dim(`Updated ${flags.lockfile}.`));
+    const written = await writeLockfile(flags.lockfile, next);
+    console.error(
+      pc2.dim(written ? `Updated ${flags.lockfile}.` : `${flags.lockfile} is already up to date.`)
+    );
   }
   const summary = summarize(findings);
   if (previous && shouldFail(findings, failOn)) {
@@ -1460,7 +1488,7 @@ cli.command("check", "Compare the current surface against the lockfile").option(
       pc2.red(`
 Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`)
     );
-    process.exitCode = 1;
+    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("--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) => {
@@ -1474,7 +1502,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
         "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
       )
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
     return;
   }
   const platform = detectPlatform(
@@ -1500,19 +1528,18 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     console.log(output);
   }
   if (failOn !== "never" && shouldFail(findings, failOn)) {
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.help();
-cli.version("0.3.0");
+cli.version("0.4.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(pc2.red(error.message));
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
   }
 }
 void main();
-//# sourceMappingURL=cli.js.map

package/dist/index.cjs

@@ -58,6 +58,7 @@ __export(src_exports, {
   formatPretty: () => formatPretty,
   routeFromFilePath: () => routeFromFilePath,
   routeFromUrl: () => routeFromUrl,
+  sameSurface: () => sameSurface,
   shouldFail: () => shouldFail,
   shouldIgnore: () => shouldIgnore,
   snapshotFromDir: () => snapshotFromDir,
@@ -1315,6 +1316,10 @@ function routeFromUrl(url) {
     return url;
   }
 }
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1333,19 +1338,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1468,6 +1486,7 @@ async function snapshotFromOrigin(origin, options = {}) {
   formatPretty,
   routeFromFilePath,
   routeFromUrl,
+  sameSurface,
   shouldFail,
   shouldIgnore,
   snapshotFromDir,
@@ -1475,4 +1494,3 @@ async function snapshotFromOrigin(origin, options = {}) {
   summarize,
   withGuidance
 });
-//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -215,6 +215,14 @@ declare const DEFAULT_AI_AGENTS: string[];
 
 declare function routeFromFilePath(root: string, filePath: string): string;
 declare function routeFromUrl(url: string): string;
+/**
+ * Whether two snapshots describe the same surface, ignoring when they were
+ * taken. The lockfile is meant to be committed, so writing a fresh timestamp on
+ * every run put a diff in front of the reviewer even when nothing had changed.
+ * That trains people to discard lockfile changes without reading them, which is
+ * the one habit this tool cannot afford.
+ */
+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>;
@@ -229,4 +237,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, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, shouldFail, shouldIgnore, snapshotFromDir, 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, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromOrigin, summarize, withGuidance };

package/dist/index.d.ts

@@ -215,6 +215,14 @@ declare const DEFAULT_AI_AGENTS: string[];
 
 declare function routeFromFilePath(root: string, filePath: string): string;
 declare function routeFromUrl(url: string): string;
+/**
+ * Whether two snapshots describe the same surface, ignoring when they were
+ * taken. The lockfile is meant to be committed, so writing a fresh timestamp on
+ * every run put a diff in front of the reviewer even when nothing had changed.
+ * That trains people to discard lockfile changes without reading them, which is
+ * the one habit this tool cannot afford.
+ */
+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>;
@@ -229,4 +237,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, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, shouldFail, shouldIgnore, snapshotFromDir, 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, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromOrigin, summarize, withGuidance };

package/dist/index.js

@@ -1246,6 +1246,10 @@ function routeFromUrl(url) {
     return url;
   }
 }
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1264,19 +1268,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1398,6 +1415,7 @@ export {
   formatPretty,
   routeFromFilePath,
   routeFromUrl,
+  sameSurface,
   shouldFail,
   shouldIgnore,
   snapshotFromDir,
@@ -1405,4 +1423,3 @@ export {
   summarize,
   withGuidance
 };
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagetrace",
-  "version": "0.3.0",
+  "version": "0.4.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": {