ssrwire 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to SSRWire are documented here. The project follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-01
+
+### Added
+
+- Offline `ssrwire compare` for two redacted JSON audits, with stable target IDs
+  for matching the same route across production and preview origins.
+- Regression, fixed, and neutral-change classification for policy findings,
+  completion, HTTP delivery, metadata values and locations, agent coverage, and
+  redirect evidence.
+- Dual-floor median timing comparisons with configurable absolute and relative
+  thresholds.
+- Terminal and deterministic JSON comparison reports plus a self-contained,
+  script-free HTML wire waterfall.
+- Public comparison, report-validation, and comparison-reporter APIs.
+
+### Changed
+
+- JSON audits now include an explicit `schemaVersion: 1` persisted-report
+  contract independent of the SSRWire package version.
+- Target objects accept an optional unique `id`; exact URL matching remains the
+  fallback when an ID is absent.
+
+## [0.3.0] - 2026-08-28
+
+### Added
+
+- Streamed capture for core Open Graph and Twitter Card metadata with arrival
+  time, observed byte position, document location, bounded repeated values, and
+  report redaction.
+- Opt-in `require.openGraph` and `require.twitterCard` target contracts with
+  missing-field, invalid-URL, duplicate/conflict, and head/body delivery
+  findings.
+- A terminal social-preview readiness table and public social metadata signal
+  types in JSON and the programmatic API.
+
+### Changed
+
+- Enabled social contracts now participate in required-signal timing,
+  cross-agent comparison, and repeated-sample stability analysis.
+- Twitter Card readiness prefers native Twitter metadata and falls back to the
+  corresponding Open Graph title, description, and image.
+- Multiple `og:image` values are retained in document order without being
+  treated as conflicting scalar metadata.
+
 ## [0.2.0] - 2026-08-24
 
 ### Added
@@ -36,6 +80,8 @@ All notable changes to SSRWire are documented here. The project follows
 - Terminal, JSON, and SARIF reports with CI-safe exit codes.
 - YAML configuration, one-off URL checks, Docker support, and GitHub Actions examples.
 
-[Unreleased]: https://github.com/lame13/ssrwire/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/lame13/ssrwire/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/lame13/ssrwire/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/lame13/ssrwire/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/lame13/ssrwire/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/lame13/ssrwire/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -26,12 +26,14 @@ before opening a pull request, then run `npm run check` again.
 Keep each change narrow. Include tests for behavior changes, especially for:
 
 - response chunk boundaries and elements split across chunks;
+- persisted audit-report validation, target matching, and comparison classification;
 - redirects, timeouts, aborted bodies, and size limits;
 - malformed, duplicated, late, or body-located metadata;
+- Open Graph and Twitter Card requirements, fallbacks, arrays, and URL values;
 - user-agent differences and comparison findings;
 - repeated-sample ordering, aggregation, and instability classification;
 - redaction of configured header values;
-- terminal, JSON, SARIF, and exit-code behavior.
+- terminal, JSON, SARIF, comparison HTML, and exit-code behavior.
 
 Do not make timing tests depend on exact millisecond values. Shared runners and
 local machines have unavoidable scheduling variance. Test ordering,

package/PUBLISHING.md

@@ -1,4 +1,4 @@
-# Publish SSRWire 0.2.0 from a local machine
+# Publish SSRWire 0.4.0 from a local machine
 
 This repository intentionally includes no npm publishing workflow. Publish from
 a foreground local terminal only after the GitHub `CI` workflow passes. Do not
@@ -10,7 +10,7 @@ request, and do not use an administrator bypass or a direct push to `main`.
 
 ## 1. Update the existing repository
 
-Work from a clean clone of the existing public repository. Copy the 0.2.0
+Work from a clean clone of the existing public repository. Copy the 0.4.0
 source files into that clone while preserving its `.git` directory.
 
 ```bash
@@ -18,7 +18,7 @@ cd ssrwire
 git switch main
 git pull --ff-only origin main
 git status --short
-git switch -c release/0.2.0
+git switch -c release/0.4.0
 ```
 
 `git status --short` must be empty before creating the release branch and
@@ -36,7 +36,7 @@ npm pack --dry-run
 node dist/bin.js --version
 ```
 
-The final command must print `0.2.0`. Inspect the dry-run file list. It must not
+The final command must print `0.4.0`. Inspect the dry-run file list. It must not
 contain `.env`, `.github`, `node_modules`, `test`, ZIP files, or tarballs.
 
 Review the release diff and version references:
@@ -45,7 +45,7 @@ Review the release diff and version references:
 git diff --check
 git diff --stat
 git diff -- package.json package-lock.json CHANGELOG.md README.md PUBLISHING.md
-rg '0\.1\.0' README.md examples package.json package-lock.json src test
+rg '0\.3\.0' README.md examples package.json package-lock.json scripts src test
 ```
 
 The final search should return nothing. Historical entries in `CHANGELOG.md`
@@ -58,10 +58,10 @@ gh auth status -h github.com || gh auth login -h github.com --web
 git add --all
 git diff --cached --check
 git diff --cached --stat
-git commit -m "feat: release SSRWire 0.2.0"
-git push --set-upstream origin release/0.2.0
-gh pr create --base main --head release/0.2.0 --fill
-PR_NUMBER="$(gh pr view release/0.2.0 --json number --jq .number)"
+git commit -m "feat: release SSRWire 0.4.0"
+git push --set-upstream origin release/0.4.0
+gh pr create --base main --head release/0.4.0 --fill
+PR_NUMBER="$(gh pr view release/0.4.0 --json number --jq .number)"
 test -n "$PR_NUMBER"
 gh pr checks "$PR_NUMBER" --watch --fail-fast
 ```
@@ -102,8 +102,8 @@ npm config get registry
 npm config get provenance
 ```
 
-The published version and `latest` tag must still be `0.1.0`. If npm already
-reports `0.2.0`, stop: never reuse a version that npm accepted.
+The published version and `latest` tag must still be `0.3.0`. If npm already
+reports `0.4.0`, stop: never reuse a version that npm accepted.
 
 In the npm package settings, select **Require two-factor authentication and
 disallow tokens**. npm documents this as the strongest package publishing
@@ -132,7 +132,7 @@ or add an npm credential to the repository or GitHub Actions. The package-level
 "disallow tokens" setting ensures that publication remains interactive.
 
 If npm's publish-time scanning delays package visibility, wait. Do not publish
-`0.2.0` again or change the tag to work around propagation.
+`0.4.0` again or change the tag to work around propagation.
 
 ## 6. Tag the exact published commit
 
@@ -140,9 +140,9 @@ If npm's publish-time scanning delays package visibility, wait. Do not publish
 node scripts/clean.mjs
 rm -rf node_modules/.vite
 git status --short
-git tag -a v0.2.0 -m "SSRWire v0.2.0"
-git push origin v0.2.0
-gh release create v0.2.0 --generate-notes --title "SSRWire v0.2.0"
+git tag -a v0.4.0 -m "SSRWire v0.4.0"
+git push origin v0.4.0
+gh release create v0.4.0 --generate-notes --title "SSRWire v0.4.0"
 ```
 
 `git status --short` must print nothing before tagging.

package/README.md

@@ -4,14 +4,14 @@
 [![npm version](https://img.shields.io/npm/v/ssrwire.svg)](https://www.npmjs.com/package/ssrwire)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Inspect streamed SSR HTML, metadata timing, and crawler-specific delivery from
-the command line.
+Inspect streamed SSR HTML, SEO and social metadata timing, and crawler-specific
+delivery from the command line.
 
 SSRWire makes a real HTTP request for each selected user-agent profile, reads
-the response incrementally, and records when important SEO signals become
-observable to its parser. It reports their elapsed time, observed byte
-position, and document location without launching a browser or executing
-JavaScript.
+the response incrementally, and records when important SEO and social-preview
+signals become observable to its parser. It reports their elapsed time,
+observed byte position, and document location without launching a browser or
+executing JavaScript.
 
 ```bash
 npx ssrwire https://example.com/product
@@ -25,7 +25,8 @@ Modern SSR output is not always one complete HTML document delivered at once:
 - a framework may intentionally stream metadata into `<body>` for a capable
   crawler while blocking for an HTML-limited bot;
 - browser, search-crawler, and social-crawler user agents may receive different
-  titles, canonicals, robots directives, redirects, or statuses;
+  titles, canonicals, social-preview metadata, robots directives, redirects, or
+  statuses;
 - the same URL and user agent may receive inconsistent SSR output between requests;
 - an interrupted or oversized stream may never deliver the expected elements;
 - a working hydrated page can hide thin or incomplete source HTML.
@@ -84,6 +85,65 @@ npx ssrwire check \
 The root command and `check` are equivalent, so `npx ssrwire URL` is the short
 form of `npx ssrwire check URL`.
 
+## Compare deployments
+
+SSRWire can compare two JSON audits without making more network requests. Give
+the same logical target a stable `id` in each environment so reports can match
+across different origins:
+
+```yaml
+# production.yml
+targets:
+  - id: home
+    url: https://www.example.com/
+  - id: pricing
+    url: https://www.example.com/pricing/
+```
+
+```yaml
+# preview.yml
+targets:
+  - id: home
+    url: https://preview.example.net/
+  - id: pricing
+    url: https://preview.example.net/pricing/
+```
+
+Capture and compare the already-redacted reports:
+
+```bash
+npx ssrwire check --config production.yml --format json --output production.json
+npx ssrwire check --config preview.yml --format json --output preview.json
+
+npx ssrwire compare production.json preview.json
+npx ssrwire compare production.json preview.json \
+  --format html \
+  --output ssrwire-diff.html
+```
+
+The comparison classifies candidate-only warning/error findings and newly
+incomplete probes as regressions, resolved findings and material timing
+improvements as fixed, and response or metadata differences as neutral changes.
+A metadata change becomes a regression when it causes a candidate policy
+finding, such as required metadata disappearing or head-only crawler metadata
+moving into the body.
+
+Timing regressions use per-agent medians and require both an absolute increase
+over 250 ms and a relative increase over 25% by default. Both floors are
+configurable on `compare`; small timing differences remain visible in the HTML
+waterfall without making CI noisy. `--fail-on regression` is the comparison
+default, while `--fail-on never` always exits successfully after valid reports
+are compared.
+
+The HTML report is one self-contained, script-free file with synchronized
+baseline and candidate milestones. It never embeds raw response HTML. SSRWire
+does not create or update baseline files automatically.
+
+Reports without target IDs match by exact target URL. IDs must be unique within
+one report, so an ID mismatch is shown as one removed and one added target
+instead of being guessed. Comparison requires the explicit `schemaVersion: 1`
+audit contract emitted by SSRWire 0.4.0.
+
 ## What it observes
 
 For each target, agent, and configured sample, SSRWire captures:
@@ -91,8 +151,8 @@ For each target, agent, and configured sample, SSRWire captures:
 - response status, final URL, redirect chain, and an allowlisted response-header snapshot;
 - time to response headers, first response-body bytes, and completed body;
 - total bytes delivered to the stream parser and a body fingerprint;
-- title, meta description, canonical, meta robots, H1, first main-content
-  text, and JSON-LD blocks;
+- title, meta description, canonical, meta robots, Open Graph, Twitter Card,
+  H1, first main-content text, and JSON-LD blocks;
 - elapsed arrival time, observed byte position, and `head`/`body` location for
   each signal;
 - clean completion, timeout, network failure, invalid response, or configured
@@ -107,10 +167,12 @@ It then checks:
 | Missing title | Error |
 | Missing description, canonical, H1, or main text | Warning |
 | Duplicate or conflicting title, description, canonical, or robots values | Warning |
+| Missing an enabled Open Graph or Twitter Card contract | Warning |
+| Invalid social metadata URL or conflicting scalar social metadata | Warning |
 | Invalid JSON-LD | Warning |
 | JSON-LD block/count exceeds the bounded analysis budget | Warning |
-| Critical metadata in `<body>` for a profile that requires head metadata | Error |
-| Status, final URL, title, canonical, or robots drift between profiles | Warning |
+| Critical or enabled social metadata in `<body>` for a profile that requires head metadata | Error |
+| Status, final URL, title, canonical, robots, or enabled social metadata drift between profiles | Warning |
 | Completion, status, final URL, or redirect-chain drift between samples | Warning |
 | Metadata value or document-location drift between complete samples | Warning |
 | Exact body fingerprint drift without metadata drift | Information |
@@ -162,6 +224,41 @@ agents:
     requiresHeadMetadata: true
 ```
 
+## Social preview metadata
+
+Every probe captures these bounded, ordered metadata signals when they arrive
+before completion or termination:
+
+- Open Graph: `og:title`, `og:type`, `og:url`, `og:image`, and
+  `og:description`;
+- Twitter Card: `twitter:card`, `twitter:title`, `twitter:description`, and
+  `twitter:image`.
+
+SSRWire accepts either the conventional `property` attribute or a `name`
+attribute for those keys. Each captured value carries the same arrival time,
+observed byte position, and document location as the existing metadata
+signals. The terminal report shows a compact readiness table whenever social
+metadata is observed or required, while JSON retains every captured value.
+
+Social policy is opt-in per target. `openGraph: true` requires the four basic
+[Open Graph protocol](https://ogp.me/) properties: title, type, URL, and image.
+The `twitterCard: true` option requires `twitter:card` plus a usable title,
+description, and image; SSRWire prefers the corresponding `twitter:*` value
+and falls back to `og:title`, `og:description`, or `og:image`. These are
+explicit SSRWire audit contracts, not a claim that a social platform will
+render a particular preview.
+
+Enabled contracts also participate in critical-signal timing, head/body
+policy, cross-agent drift, and repeated-sample stability checks. URL-valued
+fields must be absolute HTTP or HTTPS URLs. Open Graph permits multiple images,
+so SSRWire retains them in order without treating the array as a scalar
+conflict; the first non-empty image satisfies readiness.
+
+When both options are false, SSRWire still records and reports raw social
+signals but emits no social-policy or social-drift findings. It does not fetch
+images, verify dimensions or media types, execute JavaScript, or simulate a
+platform's rendered preview.
+
 ## Configuration
 
 SSRWire automatically looks for `ssrwire.config.yml`,
@@ -170,7 +267,8 @@ takes precedence.
 
 ```yaml
 targets:
-  - url: https://example.com/
+  - id: home
+    url: https://example.com/
     expectedStatus: 200
     expectedFinalUrl: https://example.com/
     require:
@@ -179,10 +277,13 @@ targets:
       canonical: true
       h1: true
       mainText: true
+      openGraph: true
+      twitterCard: true
     maxFirstByteMs: 1200
     maxCriticalMs: 2500
 
-  - url: https://example.com/not-found/
+  - id: not-found
+    url: https://example.com/not-found/
     expectedStatus: [404]
     require:
       title: true
@@ -190,6 +291,8 @@ targets:
       canonical: false
       h1: true
       mainText: true
+      openGraph: false
+      twitterCard: false
 
 agents:
   - browser
@@ -214,10 +317,15 @@ targets:
   - https://example.com/pricing/
 ```
 
+Use the object form with a stable `id` when reports from different origins will
+be compared. IDs are 1–64 ASCII letters, digits, dots, underscores, or hyphens,
+and must start with a letter or digit.
+
 Defaults:
 
 - expected status: `200`;
 - title, description, canonical, H1, and main text: required;
+- Open Graph and Twitter Card contracts: disabled;
 - agents: `browser`, `googlebot`, `bingbot`, and `twitterbot`;
 - timeout: 15 seconds per probe;
 - response limit: 10 MiB;
@@ -262,11 +370,11 @@ The final response must declare `text/html` or `application/xhtml+xml` as its
 sniff headerless, JSON, text, or binary responses for HTML-looking fragments.
 
 To keep hostile or accidentally huge pages bounded, SSRWire retains at most
-256 signals of each repeated metadata kind, analyzes at most 64 JSON-LD blocks,
-and captures at most 1,048,576 characters from one JSON-LD block. Exceeding a
-JSON-LD analysis budget produces a dedicated warning rather than being
-mislabeled as invalid JSON. The configured response-byte limit remains the
-outer bound.
+256 signals of each repeated metadata kind, including each supported social
+property, analyzes at most 64 JSON-LD blocks, and captures at most 1,048,576
+characters from one JSON-LD block. Exceeding a JSON-LD analysis budget produces
+a dedicated warning rather than being mislabeled as invalid JSON. The
+configured response-byte limit remains the outer bound.
 
 ## Timing interpretation
 
@@ -311,15 +419,18 @@ the maximum.
 
 Timing spread alone is evidence, not a failure. Network and cache variation can
 change timings without changing the response contract. SSRWire warns when HTTP
-response evidence or streamed metadata changes across samples. Exact body-hash
-variation by itself is informational because timestamps, nonces, and other
-legitimate dynamic values commonly change source HTML.
+response evidence or streamed metadata changes across samples. Enabled social
+contracts are included in metadata stability; observed social tags remain
+evidence-only when their contracts are disabled. Exact body-hash variation by
+itself is informational because timestamps, nonces, and other legitimate
+dynamic values commonly change source HTML.
 
 ## CLI reference
 
 ```text
 ssrwire [urls...] [options]
 ssrwire check [urls...] [options]
+ssrwire compare <baseline.json> <candidate.json> [options]
 ssrwire init [path] [--force]
 ```
 
@@ -342,13 +453,27 @@ Check options:
 Config-file targets and CLI URLs are combined, with exact duplicate URLs
 removed.
 
+Comparison options:
+
+| Option | Purpose |
+|---|---|
+| `-f, --format <format>` | `terminal`, `json`, or self-contained `html` |
+| `-o, --output <path>` | Write the comparison to a file |
+| `--fail-on <level>` | `regression` or `never` |
+| `--timing-regression-ms <ms>` | Absolute median slowdown floor; default `250` |
+| `--timing-regression-percent <percent>` | Relative median slowdown floor; default `25` |
+| `--no-color` | Disable terminal color |
+
 ## Reports and exit codes
 
-- `terminal`: compact sample, aggregate-timing, and finding tables for local use.
+- `terminal`: compact sample, social-readiness, aggregate-timing, and finding
+  tables for local use.
 - `json`: structured machine-readable evidence, including every probe and timing
   signal plus repeated-run stability summaries.
 - `sarif`: findings suitable for GitHub Code Scanning and other SARIF 2.1.0
   consumers.
+- comparison `html`: a script-free deployment summary and per-agent wire
+  waterfall suitable for a CI artifact.
 
 Exit codes are stable:
 
@@ -356,7 +481,11 @@ Exit codes are stable:
 - `1`: the run completed but crossed the `--fail-on` threshold;
 - `2`: configuration/setup failure or incomplete probe evidence.
 
-`--fail-on never` suppresses policy failures, but it never converts an
+For `compare`, exit `1` means at least one regression was introduced under the
+default policy, while invalid or unreadable reports use exit `2`. Neutral
+changes and fixed findings do not fail comparison.
+
+`check --fail-on never` suppresses policy failures, but it never converts an
 incomplete probe into a pass.
 
 ## GitHub Actions
@@ -414,15 +543,36 @@ const audit = await runAudit(config);
 process.stdout.write(renderJson(audit));
 ```
 
-Treat the JSON report's top-level `version` as the SSRWire software version,
-not a promise that every nested field will remain unchanged across major
-versions.
+Comparisons use the same primitives as the CLI:
+
+```ts
+import { readFile } from "node:fs/promises";
+import {
+  compareAudits,
+  parseAuditReportText,
+  renderComparisonHtml,
+} from "ssrwire";
+
+const [baselineJson, candidateJson] = await Promise.all([
+  readFile("production.json", "utf8"),
+  readFile("preview.json", "utf8"),
+]);
+const baseline = parseAuditReportText(baselineJson, "baseline audit report");
+const candidate = parseAuditReportText(candidateJson, "candidate audit report");
+const comparison = compareAudits(baseline, candidate);
+const html = renderComparisonHtml(comparison);
+```
+
+The JSON report's top-level `version` is the SSRWire software version.
+`schemaVersion` separately identifies the persisted report contract used by
+offline comparison.
 
 ## Scope
 
-SSRWire does not execute JavaScript, inspect a hydrated DOM, measure Core Web
-Vitals, discover URLs, validate indexing, bypass access controls, perform load
-testing, or emulate a crawler's rendering pipeline. Use
+SSRWire does not execute JavaScript, inspect a hydrated DOM, render social
+previews, fetch social images, measure Core Web Vitals, discover URLs, validate
+indexing, bypass access controls, perform load testing, or emulate a crawler's
+rendering pipeline. Use
 [RoutePlay](https://github.com/lame13/routeplay) for server HTML versus a cold
 browser versus real client-side navigation. Use
 [RouteLint](https://github.com/lame13/routelint) for route discovery,

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,OAAO,EACP,WAAW,EAIX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAgepB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,SAAS,OAAO,EAAE,CAuGpB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,YAAY,CA6BlF"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,OAAO,EACP,WAAW,EAMX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AA2pBpB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,SAAS,OAAO,EAAE,CAwGpB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,YAAY,CA6BlF"}