@testivai/witness 2.4.0 → 2.6.0

package/dist/capture/environment.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Capture provenance — where a capture came from.
+ *
+ * When the same URL renders differently, the question a reviewer needs
+ * answered first is whether the PAGE changed or the MACHINE did: a new
+ * browser build, another OS or distro (another set of fonts), another device
+ * scale, another way of taking the screenshot. Every adapter records the
+ * same `environment` block in the capture's metadata.json; approving a
+ * capture freezes it into the baseline's metadata.json, and the compare
+ * reads the two side by side (report/environment.ts).
+ *
+ * The block is plain JSON, so non-JS adapters write the same shape
+ * (docs/extension-api.md). Every part an adapter cannot observe is left out,
+ * never guessed: an absent field reads as "not recorded", not as a change.
+ */
+/** What the page was rendered with, measured in the page (RENDER_PROBE_EXPRESSION). */
+export interface RenderEnvironment {
+    /** CSS viewport (window.innerWidth × innerHeight). */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** window.devicePixelRatio. */
+    deviceScaleFactor?: number;
+    colorScheme?: 'light' | 'dark';
+    reducedMotion?: 'reduce' | 'no-preference';
+    /** navigator.language. */
+    locale?: string;
+    /** Intl time zone. */
+    timezone?: string;
+}
+export interface CaptureEnvironment {
+    os: {
+        /** process.platform: linux / darwin / win32. */
+        platform: string;
+        /** os.release(): the kernel on Linux, the OS version on macOS and Windows. */
+        release: string;
+        arch: string;
+        /** Linux only: `<ID> <VERSION_ID>` from /etc/os-release, e.g. "ubuntu 24.04". */
+        distro?: string;
+    };
+    browser: {
+        /** chromium / firefox / webkit (the engine family). */
+        name: string;
+        /** Full build version; null when the adapter could not read it. */
+        version: string | null;
+        /** A branded build of the engine: chrome, msedge, chrome-beta… */
+        channel?: string;
+        headless?: boolean;
+    };
+    /** The test framework driving the browser, when there is one (language only when the adapter can tell). */
+    framework?: {
+        name: string;
+        version: string | null;
+        language?: string;
+        runner?: string;
+    };
+    adapter: {
+        name: string;
+        version: string;
+        /** `<extent>:<mechanism>`, one of CAPTURE_METHODS. */
+        captureMethod: string;
+    };
+    /** The WebDriver binary, when the adapter talks to one. */
+    driver?: {
+        name: string;
+        version: string;
+    };
+    render?: RenderEnvironment;
+    ci?: {
+        provider: string;
+        runnerImage?: string;
+    };
+    /** Running inside a container (/.dockerenv or /run/.containerenv). */
+    container?: boolean;
+    /** TESTIVAI_ENV_LABEL: a name the team gives this environment, e.g. its image tag. */
+    label?: string;
+    /** Playwright project (or another runner's variant) the capture ran under. */
+    project?: string;
+    /**
+     * Native app captures only (`browser.name: "native-app"`): the device that
+     * drew the screen, from the Appium capabilities (capture/native-app.ts).
+     * `os` stays the machine the tests ran on.
+     */
+    device?: DeviceEnvironment;
+}
+/** The phone, tablet, emulator or simulator a native app capture came from. */
+export interface DeviceEnvironment {
+    /** android / ios (Appium's platformName, lowercased). */
+    platform: string;
+    /** The device OS version (platformVersion): "14", "17.5". */
+    osVersion?: string;
+    /** The hardware model the device reports (Android deviceModel): "Pixel 7", "sdk_gphone64_x86_64". */
+    model?: string;
+    /** The device name the session asked for (deviceName): "iPhone 15". */
+    name?: string;
+    /** The Appium driver (automationName): UiAutomator2, XCUITest. */
+    automation?: string;
+    /** Screen size in physical pixels (Android deviceScreenSize): "1080x2400". */
+    screen?: string;
+    /** Screen density in dpi (Android deviceScreenDensity). */
+    density?: number;
+}
+/** The machine-level part of the block: the same for every capture of a run. */
+export type HostEnvironment = Pick<CaptureEnvironment, 'os' | 'ci' | 'container' | 'label'>;
+/**
+ * How the screenshot was taken, as `<extent>:<mechanism>`. The extent is what
+ * the image covers (the full page or the viewport); the mechanism is what
+ * took it. A change of method changes the image, and often its size.
+ */
+export declare const CAPTURE_METHODS: {
+    /** CDP Page.captureScreenshot with captureBeyondViewport. */
+    readonly CDP_FULL_PAGE: "full-page:cdp";
+    /** Playwright page.screenshot({ fullPage: true }). */
+    readonly PLAYWRIGHT_FULL_PAGE: "full-page:playwright";
+    /** Viewport screenshots scrolled and stitched together. */
+    readonly STITCHED_FULL_PAGE: "full-page:stitched";
+    /** Firefox's own full-page screenshot (Selenium save_full_page_screenshot). */
+    readonly FIREFOX_FULL_PAGE: "full-page:firefox";
+    /** WebDriver takeScreenshot: the viewport only. */
+    readonly WEBDRIVER_VIEWPORT: "viewport:webdriver";
+    /** Appium takeScreenshot in a native app: the whole device screen, status bar included. */
+    readonly APPIUM_SCREEN: "screen:appium";
+};
+/** The `environmentPolicy` values in .testivai/config.json. */
+export type EnvironmentPolicy = 'warn' | 'separate' | 'strict';
+export declare const ENVIRONMENT_POLICIES: readonly EnvironmentPolicy[];
+/**
+ * The distro from /etc/os-release, as `<ID> <VERSION_ID>` ("ubuntu 24.04",
+ * "debian 12"; "arch" for a rolling release). That pair decides the fonts and
+ * the FreeType build a Linux machine draws text with; the kernel does not.
+ */
+export declare function distroFromOsRelease(text: string): string | undefined;
+/** The CI provider, and the runner image where the provider names one. */
+export declare function detectCi(env: NodeJS.ProcessEnv): CaptureEnvironment['ci'];
+/** Where collectHostEnvironment reads from; every source is injectable for tests. */
+export interface HostSources {
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    release?: string;
+    arch?: string;
+    /** Returns a file's text, or null when it cannot be read. */
+    readFile?: (filePath: string) => string | null;
+    exists?: (filePath: string) => boolean;
+}
+/** The machine-level part of the block. Never throws. */
+export declare function collectHostEnvironment(sources?: HostSources): HostEnvironment;
+/**
+ * The engine and its version from a user agent: the fallback for an adapter
+ * whose driver does not say (a Playwright persistent context has no
+ * browser() to ask). Edge is reported as chromium with channel msedge, the
+ * way Playwright names it.
+ */
+export declare function browserFromUserAgent(ua: string): CaptureEnvironment['browser'] | null;
+/**
+ * The browser (and the WebDriver binary) from W3C capabilities, as
+ * WebdriverIO's `browser.capabilities` or selenium-webdriver's
+ * `getCapabilities()` returns them (a plain object, or an object with
+ * `get()`). Headless is read from the browser's own launch arguments, and
+ * only said when they are there to say it. Null without a browser name.
+ */
+export declare function browserFromCapabilities(caps: unknown): {
+    browser: CaptureEnvironment['browser'];
+    driver?: CaptureEnvironment['driver'];
+} | null;
+/**
+ * The version of a package as the project at `root` resolves it (the user's
+ * own webdriverio or selenium-webdriver, not one bundled here), or null.
+ */
+export declare function installedPackageVersion(name: string, root?: string): string | null;
+/**
+ * One self-contained in-page expression (no imports, no closures) that
+ * measures what the page is actually rendered with. Measured, not taken from
+ * configuration: a config can say 1280×720 at scale 1 while the browser
+ * renders something else. Each field is read on its own, so one missing API
+ * never loses the rest.
+ */
+export declare const RENDER_PROBE_EXPRESSION = "(function () {\n  var out = {};\n  try { out.viewport = { width: window.innerWidth, height: window.innerHeight }; } catch (e) {}\n  try { out.deviceScaleFactor = window.devicePixelRatio; } catch (e) {}\n  try { out.colorScheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; } catch (e) {}\n  try { out.reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'reduce' : 'no-preference'; } catch (e) {}\n  try { out.locale = navigator.language; } catch (e) {}\n  try { out.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone; } catch (e) {}\n  try { out.userAgent = navigator.userAgent; } catch (e) {}\n  return out;\n})()";
+/** Validate the probe's result. Mistyped fields are dropped, never trusted. */
+export declare function parseRenderProbe(raw: unknown): {
+    render: RenderEnvironment;
+    userAgent?: string;
+} | null;
+export interface CaptureEnvironmentParts {
+    host: HostEnvironment;
+    browser: CaptureEnvironment['browser'];
+    adapter: CaptureEnvironment['adapter'];
+    framework?: CaptureEnvironment['framework'];
+    driver?: CaptureEnvironment['driver'];
+    render?: RenderEnvironment;
+    project?: string;
+    device?: DeviceEnvironment;
+}
+/** Assemble the block from what one adapter observed. */
+export declare function buildCaptureEnvironment(parts: CaptureEnvironmentParts): CaptureEnvironment;
+export interface WebDriverEnvironmentInput {
+    /** The session's capabilities (WebdriverIO browser.capabilities, Selenium getCapabilities()). */
+    capabilities: unknown;
+    /** The raw RENDER_PROBE_EXPRESSION result. */
+    probe: unknown;
+    adapter: CaptureEnvironment['adapter'];
+    framework: {
+        name: string;
+        version: string | null;
+    };
+    host?: HostEnvironment;
+}
+/**
+ * The block for a WebDriver adapter: the browser and driver from the
+ * capabilities (the user agent when they say nothing), the render settings
+ * from the probe. Null when neither names the browser: never guessed.
+ */
+export declare function webDriverEnvironment(input: WebDriverEnvironmentInput): CaptureEnvironment | null;
+/**
+ * The block as recorded in a metadata.json, or null when there is none:
+ * captures from before provenance, or from an adapter that does not record
+ * it. Only the three parts every recorder writes are required.
+ */
+export declare function readEnvironment(raw: unknown): CaptureEnvironment | null;
+/**
+ * environmentPolicy "separate" keys each snapshot by environment:
+ * `<name>__<browser>__<platform>`, the same in-the-name mechanism as the
+ * Playwright multi-project variant, so the on-disk layout, results.json, the
+ * report, approvals and the approve action all work unchanged. A browser the
+ * name already ends with (a project named after it) is not repeated. Never
+ * keyed by version: a browser upgrade should be seen, not hidden behind a
+ * fresh baseline. Other policies return the name unchanged.
+ */
+export declare function applyEnvironmentPolicyToName(name: string, env: {
+    browser: {
+        name: string;
+    };
+    os: {
+        platform: string;
+    };
+}, policy: EnvironmentPolicy | undefined): string;
+/** The variant a separate-policy name carries, or null for a name without one. */
+export declare function parseEnvironmentVariant(name: string): {
+    base: string;
+    browser: string;
+    platform: string;
+} | null;
+//# sourceMappingURL=environment.d.ts.map

package/dist/capture/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/capture/environment.ts"],"names":[],"mappings":"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"}

package/dist/capture/environment.js

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * Capture provenance — where a capture came from.
+ *
+ * When the same URL renders differently, the question a reviewer needs
+ * answered first is whether the PAGE changed or the MACHINE did: a new
+ * browser build, another OS or distro (another set of fonts), another device
+ * scale, another way of taking the screenshot. Every adapter records the
+ * same `environment` block in the capture's metadata.json; approving a
+ * capture freezes it into the baseline's metadata.json, and the compare
+ * reads the two side by side (report/environment.ts).
+ *
+ * The block is plain JSON, so non-JS adapters write the same shape
+ * (docs/extension-api.md). Every part an adapter cannot observe is left out,
+ * never guessed: an absent field reads as "not recorded", not as a change.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RENDER_PROBE_EXPRESSION = exports.ENVIRONMENT_POLICIES = exports.CAPTURE_METHODS = void 0;
+exports.distroFromOsRelease = distroFromOsRelease;
+exports.detectCi = detectCi;
+exports.collectHostEnvironment = collectHostEnvironment;
+exports.browserFromUserAgent = browserFromUserAgent;
+exports.browserFromCapabilities = browserFromCapabilities;
+exports.installedPackageVersion = installedPackageVersion;
+exports.parseRenderProbe = parseRenderProbe;
+exports.buildCaptureEnvironment = buildCaptureEnvironment;
+exports.webDriverEnvironment = webDriverEnvironment;
+exports.readEnvironment = readEnvironment;
+exports.applyEnvironmentPolicyToName = applyEnvironmentPolicyToName;
+exports.parseEnvironmentVariant = parseEnvironmentVariant;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+/**
+ * How the screenshot was taken, as `<extent>:<mechanism>`. The extent is what
+ * the image covers (the full page or the viewport); the mechanism is what
+ * took it. A change of method changes the image, and often its size.
+ */
+exports.CAPTURE_METHODS = {
+    /** CDP Page.captureScreenshot with captureBeyondViewport. */
+    CDP_FULL_PAGE: 'full-page:cdp',
+    /** Playwright page.screenshot({ fullPage: true }). */
+    PLAYWRIGHT_FULL_PAGE: 'full-page:playwright',
+    /** Viewport screenshots scrolled and stitched together. */
+    STITCHED_FULL_PAGE: 'full-page:stitched',
+    /** Firefox's own full-page screenshot (Selenium save_full_page_screenshot). */
+    FIREFOX_FULL_PAGE: 'full-page:firefox',
+    /** WebDriver takeScreenshot: the viewport only. */
+    WEBDRIVER_VIEWPORT: 'viewport:webdriver',
+    /** Appium takeScreenshot in a native app: the whole device screen, status bar included. */
+    APPIUM_SCREEN: 'screen:appium',
+};
+exports.ENVIRONMENT_POLICIES = ['warn', 'separate', 'strict'];
+// ── Host ────────────────────────────────────────────────────────────────────
+/**
+ * The distro from /etc/os-release, as `<ID> <VERSION_ID>` ("ubuntu 24.04",
+ * "debian 12"; "arch" for a rolling release). That pair decides the fonts and
+ * the FreeType build a Linux machine draws text with; the kernel does not.
+ */
+function distroFromOsRelease(text) {
+    const fields = {};
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^([A-Z_]+)=(.*)$/.exec(line.trim());
+        if (m)
+            fields[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+    if (!fields.ID)
+        return undefined;
+    return fields.VERSION_ID ? `${fields.ID} ${fields.VERSION_ID}` : fields.ID;
+}
+/** The CI provider, and the runner image where the provider names one. */
+function detectCi(env) {
+    if (env.GITHUB_ACTIONS === 'true') {
+        const runnerImage = env.ImageOS && env.ImageVersion ? `${env.ImageOS}/${env.ImageVersion}` : undefined;
+        return runnerImage ? { provider: 'github-actions', runnerImage } : { provider: 'github-actions' };
+    }
+    if (env.GITLAB_CI)
+        return { provider: 'gitlab' };
+    if (env.CIRCLECI)
+        return { provider: 'circleci' };
+    if (env.BUILDKITE)
+        return { provider: 'buildkite' };
+    if (env.JENKINS_URL)
+        return { provider: 'jenkins' };
+    if (env.TF_BUILD)
+        return { provider: 'azure-pipelines' };
+    if (env.CI && env.CI !== 'false' && env.CI !== '0')
+        return { provider: 'ci' };
+    return undefined;
+}
+const safely = (fn, fallback) => {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+};
+/** The machine-level part of the block. Never throws. */
+function collectHostEnvironment(sources = {}) {
+    const env = sources.env ?? process.env;
+    const platform = sources.platform ?? process.platform;
+    const readFile = sources.readFile ?? ((p) => safely(() => fs.readFileSync(p, 'utf-8'), null));
+    const exists = sources.exists ?? ((p) => fs.existsSync(p));
+    const host = {
+        os: {
+            platform,
+            release: sources.release ?? safely(() => os.release(), ''),
+            arch: sources.arch ?? process.arch,
+        },
+    };
+    if (platform === 'linux') {
+        const text = safely(() => readFile('/etc/os-release'), null);
+        const distro = text ? distroFromOsRelease(text) : undefined;
+        if (distro)
+            host.os.distro = distro;
+    }
+    const ci = detectCi(env);
+    if (ci)
+        host.ci = ci;
+    if (safely(() => exists('/.dockerenv') || exists('/run/.containerenv'), false))
+        host.container = true;
+    const label = (env.TESTIVAI_ENV_LABEL ?? '').trim();
+    if (label)
+        host.label = label;
+    return host;
+}
+// ── Browser ─────────────────────────────────────────────────────────────────
+/**
+ * The engine and its version from a user agent: the fallback for an adapter
+ * whose driver does not say (a Playwright persistent context has no
+ * browser() to ask). Edge is reported as chromium with channel msedge, the
+ * way Playwright names it.
+ */
+function browserFromUserAgent(ua) {
+    if (!ua)
+        return null;
+    const edge = /\bEdg\/([\d.]+)/.exec(ua);
+    const chrome = /\b(HeadlessChrome|Chrome|Chromium)\/([\d.]+)/.exec(ua);
+    if (chrome) {
+        const browser = { name: 'chromium', version: chrome[2] };
+        if (chrome[1] === 'HeadlessChrome')
+            browser.headless = true;
+        if (edge)
+            browser.channel = 'msedge';
+        return browser;
+    }
+    const firefox = /\bFirefox\/([\d.]+)/.exec(ua);
+    if (firefox)
+        return { name: 'firefox', version: firefox[1] };
+    // Two linear matches, not /Version\/([\d.]+).*Safari\//: that pattern
+    // backtracks quadratically on a long run of dots.
+    const safari = /\bVersion\/([\d.]+)/.exec(ua);
+    if (safari && /\bSafari\//.test(ua.slice(safari.index + safari[0].length)))
+        return { name: 'webkit', version: safari[1] };
+    return null;
+}
+/** WebDriver browserName values, normalized to the engine family and its branded channel. */
+const WEBDRIVER_BROWSERS = {
+    chrome: { name: 'chromium', channel: 'chrome', driver: 'chromedriver' },
+    'chrome-headless-shell': { name: 'chromium', channel: 'chrome-headless-shell', driver: 'chromedriver' },
+    chromium: { name: 'chromium', driver: 'chromedriver' },
+    microsoftedge: { name: 'chromium', channel: 'msedge', driver: 'msedgedriver' },
+    msedge: { name: 'chromium', channel: 'msedge', driver: 'msedgedriver' },
+    firefox: { name: 'firefox', driver: 'geckodriver' },
+    safari: { name: 'webkit', channel: 'safari' },
+};
+/** The first token of a driver version string ("141.0.7390.37 (hash-refs/…)" → "141.0.7390.37"). */
+const firstToken = (v) => (typeof v === 'string' && v.trim() ? v.trim().split(/\s+/)[0] : undefined);
+/**
+ * The browser (and the WebDriver binary) from W3C capabilities, as
+ * WebdriverIO's `browser.capabilities` or selenium-webdriver's
+ * `getCapabilities()` returns them (a plain object, or an object with
+ * `get()`). Headless is read from the browser's own launch arguments, and
+ * only said when they are there to say it. Null without a browser name.
+ */
+function browserFromCapabilities(caps) {
+    if (!caps || typeof caps !== 'object')
+        return null;
+    const c = caps;
+    const get = (key) => (typeof c.get === 'function' ? c.get(key) : c[key]);
+    const rawName = get('browserName');
+    if (typeof rawName !== 'string' || rawName.length === 0)
+        return null;
+    const known = WEBDRIVER_BROWSERS[rawName.toLowerCase()];
+    const version = get('browserVersion') ?? get('version');
+    const browser = {
+        name: known?.name ?? rawName.toLowerCase(),
+        version: typeof version === 'string' && version.length > 0 ? version : null,
+    };
+    if (known?.channel)
+        browser.channel = known.channel;
+    const options = (get('goog:chromeOptions') ?? get('ms:edgeOptions') ?? get('moz:firefoxOptions'));
+    if (options && Array.isArray(options.args)) {
+        browser.headless = options.args.some((a) => typeof a === 'string' && /^-{1,2}headless(=|$)/.test(a));
+    }
+    let driverVersion;
+    if (known?.driver === 'chromedriver')
+        driverVersion = firstToken(get('chrome')?.chromedriverVersion);
+    if (known?.driver === 'msedgedriver')
+        driverVersion = firstToken(get('msedge')?.msedgedriverVersion);
+    if (known?.driver === 'geckodriver')
+        driverVersion = firstToken(get('moz:geckodriverVersion'));
+    return driverVersion && known?.driver ? { browser, driver: { name: known.driver, version: driverVersion } } : { browser };
+}
+/**
+ * The version of a package as the project at `root` resolves it (the user's
+ * own webdriverio or selenium-webdriver, not one bundled here), or null.
+ */
+function installedPackageVersion(name, root = process.cwd()) {
+    try {
+        const pkgPath = require.resolve(`${name}/package.json`, { paths: [root] });
+        const version = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Render probe ────────────────────────────────────────────────────────────
+/**
+ * One self-contained in-page expression (no imports, no closures) that
+ * measures what the page is actually rendered with. Measured, not taken from
+ * configuration: a config can say 1280×720 at scale 1 while the browser
+ * renders something else. Each field is read on its own, so one missing API
+ * never loses the rest.
+ */
+exports.RENDER_PROBE_EXPRESSION = `(function () {
+  var out = {};
+  try { out.viewport = { width: window.innerWidth, height: window.innerHeight }; } catch (e) {}
+  try { out.deviceScaleFactor = window.devicePixelRatio; } catch (e) {}
+  try { out.colorScheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; } catch (e) {}
+  try { out.reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'reduce' : 'no-preference'; } catch (e) {}
+  try { out.locale = navigator.language; } catch (e) {}
+  try { out.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone; } catch (e) {}
+  try { out.userAgent = navigator.userAgent; } catch (e) {}
+  return out;
+})()`;
+const isNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isString = (v) => typeof v === 'string' && v.length > 0;
+/** Validate the probe's result. Mistyped fields are dropped, never trusted. */
+function parseRenderProbe(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const render = {};
+    const vp = r.viewport;
+    if (vp && isNumber(vp.width) && isNumber(vp.height))
+        render.viewport = { width: vp.width, height: vp.height };
+    if (isNumber(r.deviceScaleFactor))
+        render.deviceScaleFactor = r.deviceScaleFactor;
+    if (r.colorScheme === 'light' || r.colorScheme === 'dark')
+        render.colorScheme = r.colorScheme;
+    if (r.reducedMotion === 'reduce' || r.reducedMotion === 'no-preference')
+        render.reducedMotion = r.reducedMotion;
+    if (isString(r.locale))
+        render.locale = r.locale;
+    if (isString(r.timezone))
+        render.timezone = r.timezone;
+    return isString(r.userAgent) ? { render, userAgent: r.userAgent } : { render };
+}
+// ── Assembly ────────────────────────────────────────────────────────────────
+/** Drop undefined members, so the block round-trips through JSON unchanged. */
+function compact(value) {
+    const out = {};
+    for (const [k, v] of Object.entries(value))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Assemble the block from what one adapter observed. */
+function buildCaptureEnvironment(parts) {
+    const { host } = parts;
+    // Built in the documented order (docs/extension-api.md), so metadata.json reads the same everywhere.
+    const env = {
+        os: compact({ ...host.os }),
+        browser: compact({ ...parts.browser }),
+    };
+    if (parts.framework)
+        env.framework = compact({ ...parts.framework });
+    env.adapter = { ...parts.adapter };
+    if (parts.driver)
+        env.driver = { ...parts.driver };
+    if (parts.render) {
+        const render = compact({ ...parts.render });
+        if (Object.keys(render).length > 0)
+            env.render = render;
+    }
+    if (host.ci)
+        env.ci = compact({ ...host.ci });
+    if (host.container)
+        env.container = true;
+    if (host.label)
+        env.label = host.label;
+    if (parts.project)
+        env.project = parts.project;
+    if (parts.device)
+        env.device = compact({ ...parts.device });
+    return env;
+}
+/**
+ * The block for a WebDriver adapter: the browser and driver from the
+ * capabilities (the user agent when they say nothing), the render settings
+ * from the probe. Null when neither names the browser: never guessed.
+ */
+function webDriverEnvironment(input) {
+    const probed = parseRenderProbe(input.probe);
+    const fromCaps = browserFromCapabilities(input.capabilities);
+    const browser = fromCaps?.browser ?? (probed?.userAgent ? browserFromUserAgent(probed.userAgent) : null);
+    if (!browser)
+        return null;
+    return buildCaptureEnvironment({
+        host: input.host ?? collectHostEnvironment(),
+        browser,
+        framework: { ...input.framework },
+        adapter: input.adapter,
+        driver: fromCaps?.driver,
+        render: probed?.render,
+    });
+}
+/**
+ * The block as recorded in a metadata.json, or null when there is none:
+ * captures from before provenance, or from an adapter that does not record
+ * it. Only the three parts every recorder writes are required.
+ */
+function readEnvironment(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    const obj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+    if (!obj(e.os) || typeof e.os.platform !== 'string')
+        return null;
+    if (!obj(e.browser) || typeof e.browser.name !== 'string')
+        return null;
+    if (!obj(e.adapter) || typeof e.adapter.captureMethod !== 'string')
+        return null;
+    return e;
+}
+// ── separate policy ─────────────────────────────────────────────────────────
+const safeSegment = (s) => s.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase();
+/** Node's process.platform values: a suffix ending in one of them is an environment variant. */
+const PLATFORMS = ['aix', 'android', 'darwin', 'freebsd', 'haiku', 'linux', 'openbsd', 'sunos', 'win32', 'cygwin', 'netbsd'];
+/**
+ * environmentPolicy "separate" keys each snapshot by environment:
+ * `<name>__<browser>__<platform>`, the same in-the-name mechanism as the
+ * Playwright multi-project variant, so the on-disk layout, results.json, the
+ * report, approvals and the approve action all work unchanged. A browser the
+ * name already ends with (a project named after it) is not repeated. Never
+ * keyed by version: a browser upgrade should be seen, not hidden behind a
+ * fresh baseline. Other policies return the name unchanged.
+ */
+function applyEnvironmentPolicyToName(name, env, policy) {
+    if (policy !== 'separate')
+        return name;
+    const browser = safeSegment(env.browser.name);
+    const platform = safeSegment(env.os.platform);
+    const segments = name.split('__');
+    const withBrowser = segments.length > 1 && segments[segments.length - 1] === browser ? name : `${name}__${browser}`;
+    return `${withBrowser}__${platform}`;
+}
+/** The variant a separate-policy name carries, or null for a name without one. */
+function parseEnvironmentVariant(name) {
+    const segments = name.split('__');
+    if (segments.length < 3)
+        return null;
+    const platform = segments[segments.length - 1];
+    if (!PLATFORMS.includes(platform))
+        return null;
+    return { base: segments.slice(0, -2).join('__'), browser: segments[segments.length - 2], platform };
+}
+//# sourceMappingURL=environment.js.map