ssrwire 0.2.0 → 0.4.0

package/src/comparison-reporters.ts

@@ -0,0 +1,276 @@
+import type {
+  AuditComparison,
+  ComparisonChange,
+  ComparisonKind,
+  ComparisonReportFormat,
+  ComparisonTimelineEvent,
+  ComparisonTimelineSnapshot,
+  TargetComparison,
+} from "./types.js";
+
+export interface ComparisonReporterOptions {
+  readonly color?: boolean;
+}
+
+const ANSI = {
+  red: "\u001b[31m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  blue: "\u001b[36m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  reset: "\u001b[0m",
+} as const;
+
+const EVENT_SHORT_LABELS: Readonly<Record<string, string>> = {
+  headers: "H",
+  "first-byte": "B",
+  title: "T",
+  description: "D",
+  canonical: "C",
+  "open-graph": "OG",
+  "twitter-card": "X",
+  required: "R",
+  main: "M",
+  complete: "✓",
+};
+
+function paint(value: string, code: string, enabled: boolean): string {
+  return enabled ? `${code}${value}${ANSI.reset}` : value;
+}
+
+function terminalSafe(value: string): string {
+  let safe = "";
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    safe +=
+      codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)
+        ? `\\u${codePoint.toString(16).toUpperCase().padStart(4, "0")}`
+        : character;
+  }
+  return safe;
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+function stableJson(value: unknown): string {
+  return `${JSON.stringify(stableValue(value), null, 2)}\n`;
+}
+
+function kindLabel(kind: ComparisonKind): string {
+  if (kind === "regression") return "REGRESS";
+  if (kind === "fixed") return "FIXED";
+  return "CHANGED";
+}
+
+function kindColor(kind: ComparisonKind): string {
+  if (kind === "regression") return ANSI.red;
+  if (kind === "fixed") return ANSI.green;
+  return ANSI.blue;
+}
+
+function formatChange(change: ComparisonChange, color: boolean): string {
+  const label = paint(kindLabel(change.kind).padEnd(7), kindColor(change.kind), color);
+  const qualifiers = [change.agent, change.field].filter(
+    (value): value is string => value !== undefined,
+  );
+  const context = qualifiers.length === 0 ? "" : ` [${qualifiers.map(terminalSafe).join("/")}]`;
+  const values =
+    change.baseline === undefined && change.candidate === undefined
+      ? ""
+      : ` (${terminalSafe(String(change.baseline ?? "—"))} → ${terminalSafe(String(change.candidate ?? "—"))})`;
+  return `  ${label} ${terminalSafe(change.code)}${context}: ${terminalSafe(change.message)}${values}`;
+}
+
+export function renderComparisonTerminal(
+  comparison: AuditComparison,
+  options: ComparisonReporterOptions = {},
+): string {
+  const color = options.color ?? Boolean(process.stdout.isTTY);
+  const lines = [
+    paint(`SSRWire ${comparison.version} comparison`, ANSI.bold, color),
+    `${paint("Baseline", ANSI.dim, color)}: ${terminalSafe(comparison.baseline.label)} · SSRWire ${terminalSafe(comparison.baseline.version)} · ${terminalSafe(comparison.baseline.generatedAt)}`,
+    `${paint("Candidate", ANSI.dim, color)}: ${terminalSafe(comparison.candidate.label)} · SSRWire ${terminalSafe(comparison.candidate.version)} · ${terminalSafe(comparison.candidate.generatedAt)}`,
+    paint(
+      `Timing regression requires >${comparison.thresholds.timingRegressionMs} ms and >${comparison.thresholds.timingRegressionPercent}% median increase`,
+      ANSI.dim,
+      color,
+    ),
+  ];
+
+  for (const result of comparison.results) {
+    lines.push("", paint(terminalSafe(result.key), ANSI.bold, color));
+    if (result.baselineUrl !== undefined) {
+      lines.push(`  Baseline:  ${terminalSafe(result.baselineUrl)}`);
+    }
+    if (result.candidateUrl !== undefined) {
+      lines.push(`  Candidate: ${terminalSafe(result.candidateUrl)}`);
+    }
+    if (result.changes.length === 0) {
+      lines.push(paint("  No differences", ANSI.dim, color));
+    } else {
+      lines.push(...result.changes.map((change) => formatChange(change, color)));
+    }
+  }
+
+  const { summary } = comparison;
+  const summaryText =
+    `Summary: ${summary.matchedTargets} matched, ${summary.addedTargets} added, ` +
+    `${summary.removedTargets} removed, ${summary.unchangedTargets} unchanged; ` +
+    `${summary.regressions} regression(s), ${summary.fixed} fixed, ${summary.changed} changed`;
+  const summaryColor = summary.regressions > 0 ? ANSI.red : ANSI.green;
+  lines.push("", paint(summaryText, summaryColor, color));
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderComparisonJson(comparison: AuditComparison): string {
+  return stableJson(comparison);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function formatMs(value: number): string {
+  return `${Math.round(value)} ms`;
+}
+
+function maxTimelineMs(result: TargetComparison): number {
+  return Math.max(
+    1,
+    ...result.timelines.flatMap((lane) => [
+      ...(lane.baseline?.events.map((event) => event.medianMs) ?? []),
+      ...(lane.candidate?.events.map((event) => event.medianMs) ?? []),
+    ]),
+  );
+}
+
+function eventTitle(event: ComparisonTimelineEvent): string {
+  const details = [event.label, formatMs(event.medianMs)];
+  if (event.location !== undefined) details.push(event.location);
+  if (event.observedByByte !== undefined) {
+    details.push(`by byte ${Math.round(event.observedByByte)}`);
+  }
+  return details.join(" · ");
+}
+
+function renderTimelineSnapshot(
+  side: string,
+  snapshot: ComparisonTimelineSnapshot | undefined,
+  maxMs: number,
+): string {
+  if (snapshot === undefined) {
+    return `<div class="timeline-row"><div class="side">${escapeHtml(side)}</div><div class="missing">not present</div></div>`;
+  }
+  const events = snapshot.events
+    .map((event, index) => {
+      const position = Math.max(0, Math.min(100, (event.medianMs / maxMs) * 100));
+      const short = EVENT_SHORT_LABELS[event.key] ?? event.key.slice(0, 2).toUpperCase();
+      const title = escapeHtml(eventTitle(event));
+      return `<span class="event" style="--position:${position.toFixed(3)}%;--level:${index % 2}" title="${title}" aria-label="${title}" tabindex="0"><span>${escapeHtml(short)}</span></span>`;
+    })
+    .join("");
+  return `<div class="timeline-row"><div class="side">${escapeHtml(side)} <small>n=${snapshot.samples}</small></div><div class="track">${events}</div></div>`;
+}
+
+function renderTimelines(result: TargetComparison): string {
+  if (result.timelines.length === 0) return "";
+  const maxMs = maxTimelineMs(result);
+  const lanes = result.timelines
+    .map(
+      (lane) => `<section class="agent-lane">
+        <h4>${escapeHtml(lane.label)} <code>${escapeHtml(lane.agent)}</code></h4>
+        ${renderTimelineSnapshot("Baseline", lane.baseline, maxMs)}
+        ${renderTimelineSnapshot("Candidate", lane.candidate, maxMs)}
+      </section>`,
+    )
+    .join("");
+  return `<details class="waterfall" open><summary>Wire waterfall <span>0–${escapeHtml(formatMs(maxMs))}</span></summary>${lanes}</details>`;
+}
+
+function renderChange(change: ComparisonChange): string {
+  const context = [change.agent, change.field]
+    .filter((value): value is string => value !== undefined)
+    .map((value) => `<code>${escapeHtml(value)}</code>`)
+    .join(" ");
+  const values =
+    change.baseline === undefined && change.candidate === undefined
+      ? ""
+      : `<dl><div><dt>Baseline</dt><dd>${escapeHtml(String(change.baseline ?? "—"))}</dd></div><div><dt>Candidate</dt><dd>${escapeHtml(String(change.candidate ?? "—"))}</dd></div></dl>`;
+  return `<article class="change ${change.kind}">
+    <div class="change-heading"><span>${escapeHtml(kindLabel(change.kind))}</span><strong>${escapeHtml(change.code)}</strong>${context}</div>
+    <p>${escapeHtml(change.message)}</p>${values}
+  </article>`;
+}
+
+function renderTarget(result: TargetComparison): string {
+  const urls = [
+    result.baselineUrl === undefined
+      ? ""
+      : `<div><span>Baseline</span>${escapeHtml(result.baselineUrl)}</div>`,
+    result.candidateUrl === undefined
+      ? ""
+      : `<div><span>Candidate</span>${escapeHtml(result.candidateUrl)}</div>`,
+  ].join("");
+  const changes =
+    result.changes.length === 0
+      ? '<p class="clean">No differences detected.</p>'
+      : `<div class="changes">${result.changes.map(renderChange).join("")}</div>`;
+  return `<section class="target">
+    <header><div><span class="target-status">${escapeHtml(result.status)}</span><h2>${escapeHtml(result.key)}</h2></div><div class="urls">${urls}</div></header>
+    ${renderTimelines(result)}${changes}
+  </section>`;
+}
+
+export function renderComparisonHtml(comparison: AuditComparison): string {
+  const { summary } = comparison;
+  const outcome = summary.regressions > 0 ? "Regressions detected" : "No regressions";
+  const targets = comparison.results.map(renderTarget).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+  <title>SSRWire comparison · ${escapeHtml(outcome)}</title>
+  <style>
+    :root{color-scheme:light dark;--bg:#f5f2eb;--panel:#fffdf8;--ink:#191c1b;--muted:#656c68;--line:#d8d5cc;--red:#b42318;--red-bg:#fff0ed;--green:#18794e;--green-bg:#ebf8f1;--blue:#1769aa;--blue-bg:#edf6ff;--track:#e3e7e4}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}main{width:min(1180px,calc(100% - 32px));margin:0 auto;padding:48px 0 80px}.hero{display:grid;grid-template-columns:1fr auto;gap:32px;align-items:end;margin-bottom:28px}.eyebrow,.target-status{color:var(--muted);font-size:12px;font-weight:750;letter-spacing:.1em;text-transform:uppercase}h1{font-size:clamp(34px,6vw,64px);line-height:1;margin:.18em 0}.hero p{color:var(--muted);margin:0}.outcome{border:1px solid var(--line);border-radius:18px;background:var(--panel);padding:18px 22px;min-width:260px}.outcome strong{display:block;font-size:22px}.outcome.bad strong{color:var(--red)}.counts{display:grid;grid-template-columns:repeat(3,1fr);gap:10px;margin-top:12px}.counts div{border-radius:10px;padding:8px;background:var(--bg)}.counts b{display:block;font-size:20px}.counts span{color:var(--muted);font-size:12px}.sources{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-bottom:28px}.source,.target{background:var(--panel);border:1px solid var(--line);border-radius:18px}.source{padding:16px 18px}.source span,.urls span{display:block;color:var(--muted);font-size:12px;text-transform:uppercase;letter-spacing:.08em}.source strong{display:block;font-size:17px}.source small{color:var(--muted)}.threshold{color:var(--muted);font-size:13px;margin:-14px 0 28px}.target{overflow:hidden;margin:18px 0}.target>header{display:grid;grid-template-columns:minmax(180px,.55fr) 1fr;gap:24px;padding:22px 24px;border-bottom:1px solid var(--line)}.target h2{font-size:23px;margin:3px 0 0;overflow-wrap:anywhere}.urls{display:grid;gap:8px;overflow-wrap:anywhere}.waterfall{padding:18px 24px;border-bottom:1px solid var(--line)}.waterfall summary{cursor:pointer;font-weight:700}.waterfall summary span{color:var(--muted);font-weight:400;margin-left:8px}.agent-lane{margin:18px 0}.agent-lane h4{margin:0 0 8px}.agent-lane code,.change-heading code{color:var(--muted);font-size:12px}.timeline-row{display:grid;grid-template-columns:126px 1fr;align-items:center;margin:5px 0}.side{color:var(--muted);font-size:13px}.side small{opacity:.75}.track{position:relative;height:48px;border-radius:8px;background:linear-gradient(90deg,var(--track),transparent 1px) 0 0/10% 100%,color-mix(in srgb,var(--track) 55%,transparent)}.event{position:absolute;left:var(--position);top:calc(5px + var(--level)*20px);transform:translateX(-50%);cursor:help}.event:focus-visible{outline:2px solid var(--blue);outline-offset:2px}.event:before{content:"";position:absolute;left:50%;top:-5px;height:42px;border-left:1px solid color-mix(in srgb,var(--ink) 22%,transparent);z-index:0}.event span{position:relative;display:block;min-width:20px;padding:1px 4px;border:1px solid var(--line);border-radius:5px;background:var(--panel);font-size:10px;font-weight:800;text-align:center;z-index:1}.missing{color:var(--muted);font-size:13px}.changes{display:grid;gap:10px;padding:18px 24px 24px}.change{border-left:4px solid var(--blue);border-radius:8px;background:var(--blue-bg);padding:12px 14px}.change.regression{border-color:var(--red);background:var(--red-bg)}.change.fixed{border-color:var(--green);background:var(--green-bg)}.change-heading{display:flex;align-items:center;gap:9px;flex-wrap:wrap}.change-heading>span{font-size:11px;font-weight:850;letter-spacing:.08em}.change p{margin:5px 0 0}.change dl{display:grid;grid-template-columns:1fr 1fr;gap:8px;margin:10px 0 0}.change dl div{min-width:0;padding:7px 9px;border-radius:6px;background:color-mix(in srgb,var(--panel) 70%,transparent)}dt{color:var(--muted);font-size:11px;text-transform:uppercase}dd{margin:1px 0 0;overflow-wrap:anywhere}.clean{color:var(--green);font-weight:700;padding:18px 24px;margin:0}.legend{color:var(--muted);font-size:12px;margin-top:30px}.legend code{color:var(--ink)}@media(max-width:720px){main{width:min(100% - 20px,1180px);padding-top:24px}.hero,.sources,.target>header{grid-template-columns:1fr}.outcome{min-width:0}.timeline-row{grid-template-columns:1fr}.side{margin-bottom:3px}.change dl{grid-template-columns:1fr}}
+    @media(prefers-color-scheme:dark){:root{--bg:#151817;--panel:#1d211f;--ink:#f0f3f1;--muted:#aab2ad;--line:#363d39;--red:#ff8a80;--red-bg:#321d1a;--green:#73d6a6;--green-bg:#173125;--blue:#75bfff;--blue-bg:#172a3a;--track:#323a36}}
+  </style>
+</head>
+<body><main>
+  <section class="hero"><div><div class="eyebrow">SSRWire ${escapeHtml(comparison.version)} · deployment diff</div><h1>${escapeHtml(outcome)}</h1><p>Generated ${escapeHtml(comparison.generatedAt)}</p></div><aside class="outcome ${summary.regressions > 0 ? "bad" : "good"}"><strong>${summary.regressions} regression${summary.regressions === 1 ? "" : "s"}</strong><div class="counts"><div><b>${summary.fixed}</b><span>fixed</span></div><div><b>${summary.changed}</b><span>changed</span></div><div><b>${summary.unchangedTargets}</b><span>unchanged</span></div></div></aside></section>
+  <section class="sources"><div class="source"><span>Baseline</span><strong>${escapeHtml(comparison.baseline.label)}</strong><small>SSRWire ${escapeHtml(comparison.baseline.version)} · ${escapeHtml(comparison.baseline.generatedAt)} · repeat ${comparison.baseline.repeat}</small></div><div class="source"><span>Candidate</span><strong>${escapeHtml(comparison.candidate.label)}</strong><small>SSRWire ${escapeHtml(comparison.candidate.version)} · ${escapeHtml(comparison.candidate.generatedAt)} · repeat ${comparison.candidate.repeat}</small></div></section>
+  <p class="threshold">Timing regressions require both &gt;${comparison.thresholds.timingRegressionMs} ms and &gt;${comparison.thresholds.timingRegressionPercent}% median increase.</p>
+  ${targets || '<section class="target"><p class="clean">Both reports contain no targets.</p></section>'}
+  <p class="legend"><code>H</code> headers · <code>B</code> first byte · <code>T</code> title · <code>D</code> description · <code>C</code> canonical · <code>OG</code> Open Graph ready · <code>X</code> Twitter Card ready · <code>R</code> required signals ready · <code>M</code> main text · <code>✓</code> complete. Hover markers for timing, location, and byte evidence.</p>
+</main></body></html>\n`;
+}
+
+export function renderComparisonReport(
+  comparison: AuditComparison,
+  format: ComparisonReportFormat,
+  options: ComparisonReporterOptions = {},
+): string {
+  if (format === "terminal") return renderComparisonTerminal(comparison, options);
+  if (format === "json") return renderComparisonJson(comparison);
+  if (format === "html") return renderComparisonHtml(comparison);
+
+  const exhaustive: never = format;
+  return exhaustive;
+}

package/src/config.ts

@@ -23,11 +23,17 @@ const requireSchema = z
     canonical: z.boolean().optional(),
     h1: z.boolean().optional(),
     mainText: z.boolean().optional(),
+    openGraph: z.boolean().optional(),
+    twitterCard: z.boolean().optional(),
   })
   .strict();
 
 const targetObjectSchema = z
   .object({
+    id: z
+      .string()
+      .regex(/^[a-z0-9][a-z0-9._-]{0,63}$/i)
+      .optional(),
     url: z.string().min(1),
     expectedStatus: z
       .union([
@@ -129,11 +135,14 @@ function normalizeTarget(value: string | z.infer<typeof targetObjectSchema>): Au
     requireCanonical: required?.canonical ?? true,
     requireH1: required?.h1 ?? true,
     requireMainText: required?.mainText ?? true,
+    requireOpenGraph: required?.openGraph ?? false,
+    requireTwitterCard: required?.twitterCard ?? false,
     ...(item.maxFirstByteMs === undefined ? {} : { maxFirstByteMs: item.maxFirstByteMs }),
     ...(item.maxCriticalMs === undefined ? {} : { maxCriticalMs: item.maxCriticalMs }),
   };
 
   return {
+    ...(item.id === undefined ? {} : { id: item.id }),
     url: validateHttpUrl(item.url, "target URL"),
     expectations,
   };
@@ -255,13 +264,22 @@ async function readConfig(path: string | undefined): Promise<FileConfig> {
 
 function uniqueTargets(targets: readonly AuditTarget[]): readonly AuditTarget[] {
   const seen = new Set<string>();
-  return targets.filter((target) => {
+  const unique = targets.filter((target) => {
     if (seen.has(target.url)) {
       return false;
     }
     seen.add(target.url);
     return true;
   });
+  const ids = new Set<string>();
+  for (const target of unique) {
+    if (target.id === undefined) continue;
+    if (ids.has(target.id)) {
+      throw new ConfigError(`Target id ${target.id} is duplicated.`);
+    }
+    ids.add(target.id);
+  }
+  return unique;
 }
 
 export async function loadConfig(options: LoadConfigOptions = {}): Promise<SsrWireConfig> {

package/src/http-probe.ts

@@ -55,6 +55,7 @@ function emptySignals(): DocumentSignals {
     descriptions: [],
     canonicals: [],
     robots: [],
+    socialMetadata: [],
     h1s: [],
     jsonLd: [],
   };
@@ -91,6 +92,9 @@ function redactSignals(signals: DocumentSignals, redaction: RedactionPlan): Docu
     descriptions: signals.descriptions.map(element),
     canonicals: signals.canonicals.map(element),
     robots: signals.robots.map(element),
+    ...(signals.socialMetadata === undefined
+      ? {}
+      : { socialMetadata: signals.socialMetadata.map(element) }),
     h1s: signals.h1s.map(element),
     ...(signals.firstMainText === undefined
       ? {}

package/src/index.ts

@@ -1,6 +1,19 @@
 export { BUILTIN_AGENTS, resolveAgent, resolveAgents } from "./agents.js";
 export { analyzeTarget, summarizeAudit } from "./analyze.js";
 export { runAudit } from "./audit.js";
+export {
+  AUDIT_SCHEMA_VERSION,
+  AuditReportError,
+  parseAuditReport,
+  parseAuditReportText,
+} from "./audit-report.js";
+export { ComparisonError, compareAudits } from "./compare.js";
+export {
+  renderComparisonHtml,
+  renderComparisonJson,
+  renderComparisonReport,
+  renderComparisonTerminal,
+} from "./comparison-reporters.js";
 export { loadConfig, parseHeaderOption } from "./config.js";
 export { probeUrl } from "./http-probe.js";
 export { redactProbe } from "./redact.js";
@@ -9,9 +22,21 @@ export { createStreamInspector } from "./stream-parser.js";
 export type {
   AgentProfile,
   AgentStability,
+  AuditComparison,
+  AuditReportDescriptor,
   AuditResult,
   AuditSummary,
   AuditTarget,
+  CompareAuditOptions,
+  ComparisonChange,
+  ComparisonKind,
+  ComparisonReportFormat,
+  ComparisonScope,
+  ComparisonSummary,
+  ComparisonThresholds,
+  ComparisonTimelineEvent,
+  ComparisonTimelineLane,
+  ComparisonTimelineSnapshot,
   DocumentSignals,
   ElementLocation,
   ElementSignal,
@@ -27,10 +52,14 @@ export type {
   RobotsAudience,
   RobotsSignal,
   Severity,
+  SocialMetadataProperty,
+  SocialMetadataSignal,
   SsrWireConfig,
   StabilityTimings,
   StabilityVariants,
   TargetAuditResult,
+  TargetComparison,
+  TargetComparisonStatus,
   TargetExpectations,
   TimingMark,
   TimingStats,

package/src/redact.ts

@@ -90,6 +90,11 @@ function redactSignals(signals: DocumentSignals, plan: RedactionPlan): DocumentS
     descriptions: signals.descriptions.map((signal) => redactElement(signal, plan)),
     canonicals: signals.canonicals.map((signal) => redactElement(signal, plan)),
     robots: signals.robots.map((signal) => redactElement(signal, plan)),
+    ...(signals.socialMetadata === undefined
+      ? {}
+      : {
+          socialMetadata: signals.socialMetadata.map((signal) => redactElement(signal, plan)),
+        }),
     h1s: signals.h1s.map((signal) => redactElement(signal, plan)),
     ...(signals.firstMainText === undefined
       ? {}
@@ -151,6 +156,7 @@ export function redactAudit(audit: AuditResult, secrets: readonly string[]): Aud
     results: audit.results.map((result) => ({
       target: {
         ...result.target,
+        ...(result.target.id === undefined ? {} : { id: redactText(result.target.id, plan) }),
         url: redactText(result.target.url, plan),
         expectations: {
           ...result.target.expectations,

package/src/reporters.ts

@@ -1,3 +1,9 @@
+import {
+  effectiveTwitterCardSignal,
+  firstSocialSignal,
+  OPEN_GRAPH_REQUIRED_PROPERTIES,
+  TWITTER_CARD_REQUIRED_FIELDS,
+} from "./social.js";
 import type {
   AgentStability,
   AuditResult,
@@ -86,6 +92,31 @@ function probeRow(probe: ProbeResult, showSample: boolean): readonly string[] {
   ];
 }
 
+function formatSignalSet(signals: readonly (ElementSignal | undefined)[]): string {
+  const present = signals.filter((signal): signal is ElementSignal => signal !== undefined);
+  if (present.length < signals.length) return `${present.length}/${signals.length}`;
+  const arrivalMs = Math.max(...present.map((signal) => signal.atMs));
+  const location = present.some((signal) => signal.location === "body")
+    ? "body"
+    : present.some((signal) => signal.location === "document")
+      ? "document"
+      : "head";
+  return `${Math.round(arrivalMs)} ms/${location}`;
+}
+
+function socialRow(probe: ProbeResult, showSample: boolean): readonly string[] {
+  return [
+    ...(showSample ? [String(probe.sample ?? "—")] : []),
+    truncate(probe.agent.label, 24),
+    formatSignalSet(
+      OPEN_GRAPH_REQUIRED_PROPERTIES.map((property) => firstSocialSignal(probe.signals, property)),
+    ),
+    formatSignalSet(
+      TWITTER_CARD_REQUIRED_FIELDS.map((field) => effectiveTwitterCardSignal(probe.signals, field)),
+    ),
+  ];
+}
+
 function stabilityRows(stability: readonly AgentStability[]): readonly (readonly string[])[] {
   const labels: Readonly<Record<keyof AgentStability["timings"], string>> = {
     headers: "Headers",
@@ -171,6 +202,21 @@ export function renderTerminal(audit: AuditResult, options: ReporterOptions = {}
       ),
     );
 
+    const showSocial =
+      result.target.expectations.requireOpenGraph === true ||
+      result.target.expectations.requireTwitterCard === true ||
+      result.probes.some((probe) => (probe.signals.socialMetadata?.length ?? 0) > 0);
+    if (showSocial) {
+      lines.push(
+        "",
+        "Social preview readiness",
+        renderTable(
+          [...(showSample ? ["Sample"] : []), "Agent", "Open Graph", "Twitter Card"],
+          result.probes.map((probe) => socialRow(probe, showSample)),
+        ),
+      );
+    }
+
     if (result.stability !== undefined) {
       const rows = stabilityRows(result.stability);
       if (rows.length > 0) {

package/src/social.ts

@@ -0,0 +1,116 @@
+import type { DocumentSignals, SocialMetadataProperty, SocialMetadataSignal } from "./types.js";
+
+export const SOCIAL_METADATA_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+  "og:description",
+  "twitter:card",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const OPEN_GRAPH_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+  "og:description",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const OPEN_GRAPH_REQUIRED_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const TWITTER_PROPERTIES = [
+  "twitter:card",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const TWITTER_CARD_REQUIRED_FIELDS = ["card", "title", "description", "image"] as const;
+export type TwitterCardField = (typeof TWITTER_CARD_REQUIRED_FIELDS)[number];
+
+const SOCIAL_METADATA_PROPERTY_SET = new Set<string>(SOCIAL_METADATA_PROPERTIES);
+const SOCIAL_URL_PROPERTY_SET = new Set<SocialMetadataProperty>([
+  "og:url",
+  "og:image",
+  "twitter:image",
+]);
+
+export function isSocialMetadataProperty(
+  value: string | undefined,
+): value is SocialMetadataProperty {
+  return value !== undefined && SOCIAL_METADATA_PROPERTY_SET.has(value);
+}
+
+export function socialSignals(
+  signals: DocumentSignals,
+  property: SocialMetadataProperty,
+): readonly SocialMetadataSignal[] {
+  return (signals.socialMetadata ?? []).filter((signal) => signal.property === property);
+}
+
+export function firstSocialSignal(
+  signals: DocumentSignals,
+  property: SocialMetadataProperty,
+): SocialMetadataSignal | undefined {
+  return socialSignals(signals, property).find((signal) => signal.value.trim().length > 0);
+}
+
+export function effectiveTwitterCardSignal(
+  signals: DocumentSignals,
+  field: TwitterCardField,
+): SocialMetadataSignal | undefined {
+  if (field === "card") return firstSocialSignal(signals, "twitter:card");
+  if (field === "title") {
+    return firstSocialSignal(signals, "twitter:title") ?? firstSocialSignal(signals, "og:title");
+  }
+  if (field === "description") {
+    return (
+      firstSocialSignal(signals, "twitter:description") ??
+      firstSocialSignal(signals, "og:description")
+    );
+  }
+  return firstSocialSignal(signals, "twitter:image") ?? firstSocialSignal(signals, "og:image");
+}
+
+export function normalizeSocialValue(
+  property: SocialMetadataProperty,
+  value: string,
+  baseUrl: string,
+): string {
+  const normalized = value.trim().replace(/\s+/gu, " ");
+  if (normalized.length === 0) return "";
+  if (SOCIAL_URL_PROPERTY_SET.has(property)) {
+    try {
+      const url = new URL(normalized, baseUrl);
+      url.hash = "";
+      return url.href;
+    } catch {
+      return normalized;
+    }
+  }
+  return property === "og:type" || property === "twitter:card"
+    ? normalized.toLowerCase()
+    : normalized;
+}
+
+export function isAbsoluteHttpSocialUrl(value: string): boolean {
+  try {
+    const url = new URL(value.trim());
+    return (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.username.length === 0 &&
+      url.password.length === 0
+    );
+  } catch {
+    return false;
+  }
+}