ssrwire 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+export type Severity = "info" | "warning" | "error";
+export type ElementLocation = "head" | "body" | "document";
+export interface TimingMark {
+    readonly atMs: number;
+    readonly observedByByte: number;
+}
+export interface ElementSignal extends TimingMark {
+    readonly value: string;
+    readonly location: ElementLocation;
+}
+export type RobotsAudience = "robots" | "googlebot" | "bingbot";
+export interface RobotsSignal extends ElementSignal {
+    readonly audience: RobotsAudience;
+}
+export interface JsonLdSignal extends TimingMark {
+    readonly location: ElementLocation;
+    readonly valid?: boolean;
+    readonly types: readonly string[];
+    readonly bytes: number;
+    readonly analysisLimit?: string;
+    readonly error?: string;
+}
+export interface DocumentSignals {
+    readonly title?: ElementSignal;
+    readonly titles?: readonly ElementSignal[];
+    readonly descriptions: readonly ElementSignal[];
+    readonly canonicals: readonly ElementSignal[];
+    readonly robots: readonly RobotsSignal[];
+    readonly h1s: readonly ElementSignal[];
+    readonly firstMainText?: ElementSignal;
+    readonly jsonLd: readonly JsonLdSignal[];
+    readonly headClosed?: TimingMark;
+    readonly bodyStarted?: TimingMark;
+    readonly documentClosed?: TimingMark;
+}
+export interface AgentProfile {
+    readonly key: string;
+    readonly label: string;
+    readonly userAgent: string;
+    readonly requiresHeadMetadata: boolean;
+}
+export interface RedirectHop {
+    readonly url: string;
+    readonly status: number;
+    readonly location: string;
+    readonly durationMs: number;
+}
+export interface HeaderSnapshot {
+    readonly values: Readonly<Record<string, string>>;
+    readonly setCookiePresent: boolean;
+}
+export interface ProbeTimings {
+    readonly headersMs: number;
+    readonly firstByteMs?: number;
+    readonly completeMs?: number;
+}
+export type ProbeCompletion = "complete" | "max-bytes-exceeded" | "timeout" | "network-error" | "invalid-response";
+export interface ProbeOptions {
+    readonly url: string;
+    readonly agent: AgentProfile;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly maxBytes: number;
+    readonly maxRedirects: number;
+    /** Keep reflected header values internal so callers can analyze raw evidence before redaction. */
+    readonly redactHeaderValues?: boolean;
+}
+export interface ProbeResult {
+    readonly requestedUrl: string;
+    readonly finalUrl: string;
+    readonly agent: AgentProfile;
+    readonly status?: number;
+    readonly redirects: readonly RedirectHop[];
+    readonly headers: HeaderSnapshot;
+    readonly timings: ProbeTimings;
+    readonly bytesRead: number;
+    readonly bodySha256?: string;
+    readonly signals: DocumentSignals;
+    readonly completion: ProbeCompletion;
+    readonly error?: string;
+}
+export interface TargetExpectations {
+    readonly statuses: readonly number[];
+    readonly finalUrl?: string;
+    readonly requireTitle: boolean;
+    readonly requireDescription: boolean;
+    readonly requireCanonical: boolean;
+    readonly requireH1: boolean;
+    readonly requireMainText: boolean;
+    readonly maxFirstByteMs?: number;
+    readonly maxCriticalMs?: number;
+}
+export interface AuditTarget {
+    readonly url: string;
+    readonly expectations: TargetExpectations;
+}
+export interface SsrWireConfig {
+    readonly targets: readonly AuditTarget[];
+    readonly agents: readonly AgentProfile[];
+    readonly headers: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly maxBytes: number;
+    readonly maxRedirects: number;
+}
+export interface Finding {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly message: string;
+    readonly url: string;
+    readonly agent?: string;
+    readonly evidence?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface TargetAuditResult {
+    readonly target: AuditTarget;
+    readonly probes: readonly ProbeResult[];
+    readonly findings: readonly Finding[];
+}
+export interface AuditSummary {
+    readonly targets: number;
+    readonly probes: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly info: number;
+    readonly incomplete: number;
+}
+export interface AuditResult {
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly durationMs: number;
+    readonly results: readonly TargetAuditResult[];
+    readonly summary: AuditSummary;
+}
+export type ReportFormat = "terminal" | "json" | "sarif";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,SAAS,aAAa,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,oBAAoB,GACpB,SAAS,GACT,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,OAAO,QAA2B,CAAC"}

package/dist/version.js

@@ -0,0 +1,14 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+function readVersion(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "version" in value &&
+        typeof value.version === "string") {
+        return value.version;
+    }
+    throw new Error("SSRWire could not read its package version.");
+}
+export const VERSION = readVersion(packageJson);
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAY,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAExD,SAAS,WAAW,CAAC,KAAc;IACjC,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EACjC,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC"}

package/examples/github-actions.yml

@@ -0,0 +1,73 @@
+name: SSRWire
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          package-manager-cache: false
+
+      - name: Run SSRWire (pull request, no credentials)
+        id: ssrwire_pr
+        if: github.event_name == 'pull_request'
+        continue-on-error: true
+        run: >-
+          npx --yes ssrwire@0.1.0 check
+          --config ssrwire.config.yml
+          --format sarif
+          --output reports/ssrwire.sarif
+          --fail-on error
+
+      - name: Run SSRWire (trusted branch)
+        id: ssrwire_trusted
+        if: github.event_name != 'pull_request'
+        continue-on-error: true
+        run: >-
+          npx --yes ssrwire@0.1.0 check
+          --config ssrwire.config.yml
+          --format sarif
+          --output reports/ssrwire.sarif
+          --fail-on error
+        env:
+          PREVIEW_TOKEN: ${{ secrets.PREVIEW_TOKEN }}
+
+      - name: Upload SARIF
+        if: >-
+          always() &&
+          hashFiles('reports/ssrwire.sarif') != '' &&
+          github.event.repository.visibility == 'public' &&
+          (github.event_name != 'pull_request' ||
+          github.event.pull_request.head.repo.full_name == github.repository)
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: reports/ssrwire.sarif
+
+      - name: Keep the report as a workflow artifact
+        if: always() && hashFiles('reports/ssrwire.sarif') != ''
+        uses: actions/upload-artifact@v7
+        with:
+          name: ssrwire-sarif
+          path: reports/ssrwire.sarif
+          retention-days: 14
+
+      - name: Enforce SSRWire result
+        if: >-
+          always() &&
+          (steps.ssrwire_pr.outcome == 'failure' ||
+          steps.ssrwire_trusted.outcome == 'failure')
+        run: exit 1

package/examples/ssrwire.config.yml

@@ -0,0 +1,37 @@
+# Replace these URLs with a small set of high-value SSR routes.
+targets:
+  - url: https://example.com/
+    expectedStatus: 200
+    expectedFinalUrl: https://example.com/
+    require:
+      title: true
+      description: true
+      canonical: true
+      h1: true
+      mainText: true
+
+  - url: https://example.com/pricing/
+    expectedStatus: 200
+    require:
+      title: true
+      description: true
+      canonical: true
+      h1: true
+      mainText: true
+
+# Add maxFirstByteMs or maxCriticalMs per target only when the runner location
+# and cache state are stable enough for a meaningful threshold.
+
+agents:
+  - browser
+  - googlebot
+  - bingbot
+  - twitterbot
+
+timeoutMs: 15000
+maxBytes: 10485760
+maxRedirects: 10
+
+# Keep preview credentials in a CI secret or exported environment variable.
+# headers:
+#   x-preview-token: "${PREVIEW_TOKEN}"

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "ssrwire",
+  "version": "0.1.0",
+  "description": "Inspect streamed SSR HTML, metadata timing, and crawler-specific delivery from the command line.",
+  "type": "module",
+  "bin": {
+    "ssrwire": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "PUBLISHING.md"
+  ],
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json",
+    "check": "npm run lint && npm run typecheck && npm run test && npm run build && npm run package:check",
+    "dev": "tsx src/bin.ts",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "package:check": "node scripts/package-check.mjs",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "ssr",
+    "seo",
+    "technical-seo",
+    "streaming-html",
+    "nextjs",
+    "nuxt",
+    "astro",
+    "crawler",
+    "cli",
+    "typescript",
+    "seo-tools",
+    "github-actions",
+    "sarif"
+  ],
+  "author": {
+    "name": "Niko M.",
+    "url": "https://nikom.work"
+  },
+  "homepage": "https://nikom.work",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lame13/ssrwire.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lame13/ssrwire/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "fsevents": false
+  },
+  "dependencies": {
+    "commander": "14.0.0",
+    "htmlparser2": "10.0.0",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "22.20.1",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,129 @@
+import type { AgentProfile } from "./types.js";
+
+export const BUILTIN_AGENTS: Readonly<Record<string, AgentProfile>> = Object.freeze({
+  browser: Object.freeze({
+    key: "browser",
+    label: "Browser",
+    userAgent:
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    requiresHeadMetadata: false,
+  }),
+  googlebot: Object.freeze({
+    key: "googlebot",
+    label: "Googlebot",
+    userAgent: "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
+    requiresHeadMetadata: false,
+  }),
+  bingbot: Object.freeze({
+    key: "bingbot",
+    label: "Bingbot",
+    userAgent: "Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)",
+    requiresHeadMetadata: true,
+  }),
+  twitterbot: Object.freeze({
+    key: "twitterbot",
+    label: "Twitterbot",
+    userAgent: "Twitterbot/1.0",
+    requiresHeadMetadata: true,
+  }),
+  facebook: Object.freeze({
+    key: "facebook",
+    label: "Facebook crawler",
+    userAgent: "facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)",
+    requiresHeadMetadata: true,
+  }),
+});
+
+export type BuiltinAgentKey = "browser" | "googlebot" | "bingbot" | "twitterbot" | "facebook";
+export type AgentInput =
+  | string
+  | {
+      readonly key: string;
+      readonly label?: string;
+      readonly userAgent: string;
+      readonly requiresHeadMetadata?: boolean;
+    };
+
+const ALIASES: Readonly<Record<string, BuiltinAgentKey>> = Object.freeze({
+  browser: "browser",
+  chrome: "browser",
+  google: "googlebot",
+  googlebot: "googlebot",
+  bing: "bingbot",
+  bingbot: "bingbot",
+  twitter: "twitterbot",
+  twitterbot: "twitterbot",
+  x: "twitterbot",
+  facebook: "facebook",
+  facebookbot: "facebook",
+  facebookexternalhit: "facebook",
+});
+
+function isCustomAgent(value: unknown): value is Exclude<AgentInput, string> {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as {
+    readonly key?: unknown;
+    readonly label?: unknown;
+    readonly userAgent?: unknown;
+    readonly requiresHeadMetadata?: unknown;
+  };
+  return (
+    typeof candidate.key === "string" &&
+    candidate.key.trim().length > 0 &&
+    typeof candidate.userAgent === "string" &&
+    candidate.userAgent.trim().length > 0 &&
+    (candidate.label === undefined ||
+      (typeof candidate.label === "string" && candidate.label.trim().length > 0)) &&
+    (candidate.requiresHeadMetadata === undefined ||
+      typeof candidate.requiresHeadMetadata === "boolean")
+  );
+}
+
+/** Resolve a built-in key/alias or validate a complete custom agent profile. */
+export function resolveAgent(input: AgentInput): AgentProfile {
+  if (typeof input === "string") {
+    const normalized = input.trim().toLowerCase();
+    const key = ALIASES[normalized];
+    if (key === undefined) {
+      throw new Error(
+        `Unknown agent "${input}". Use browser, googlebot, bingbot, twitterbot, facebook, or a custom agent object.`,
+      );
+    }
+    const agent = BUILTIN_AGENTS[key];
+    if (agent === undefined) {
+      throw new Error(`Built-in agent "${key}" is unavailable.`);
+    }
+    return agent;
+  }
+
+  if (!isCustomAgent(input)) {
+    throw new TypeError(
+      "Custom agents require non-empty key and userAgent strings; label and requiresHeadMetadata are optional.",
+    );
+  }
+
+  if (/[\r\n]/u.test(input.userAgent)) {
+    throw new TypeError("Custom agent userAgent cannot contain a line break.");
+  }
+
+  return Object.freeze({
+    key: input.key.trim(),
+    label: input.label?.trim() ?? input.key.trim(),
+    userAgent: input.userAgent.trim(),
+    requiresHeadMetadata: input.requiresHeadMetadata ?? false,
+  });
+}
+
+/** Resolve an ordered list and reject duplicate keys, which would make reports ambiguous. */
+export function resolveAgents(inputs: readonly AgentInput[]): AgentProfile[] {
+  const resolved = inputs.map(resolveAgent);
+  const seen = new Set<string>();
+  for (const agent of resolved) {
+    const normalized = agent.key.toLowerCase();
+    if (seen.has(normalized)) {
+      throw new Error(`Duplicate agent key "${agent.key}".`);
+    }
+    seen.add(normalized);
+  }
+  return resolved;
+}