humanish 0.105.0 → 0.106.1

package/dist/actors/scripted-browser/journey.js

@@ -0,0 +1,171 @@
+// Parse a scenario's `browser.steps` into a BrowserPersonaJourney: the actions, text assertions and
+// expectations the scripted browser runs. The journey is the actor's whole behavior.
+import path from "node:path";
+export function parseBrowserPersonaJourneyFromScenario(args) {
+    if (!isRecord(args.raw)) {
+        return {};
+    }
+    const scenarioId = publicSafeToken(stringValue(args.raw.id), path.basename(args.relativePath, path.extname(args.relativePath)));
+    const scenarioTitle = stringValue(args.raw.title) ?? scenarioId;
+    const goal = stringValue(args.raw.goal) ?? "Drive a public-safe browser persona through the local app.";
+    const browser = isRecord(args.raw.browser) ? args.raw.browser : undefined;
+    const declaredBrowser = args.raw.mode === "browser" || browser !== undefined || hasInlineBrowserSteps(args.raw.steps);
+    if (!declaredBrowser) {
+        return {};
+    }
+    let startPath = "/";
+    let rawSteps = [];
+    if (browser !== undefined) {
+        const parsedStartPath = stringValue(browser.startPath) ?? stringValue(browser.start_path);
+        if (parsedStartPath !== undefined) {
+            startPath = parsedStartPath;
+        }
+        if (Array.isArray(browser.steps)) {
+            rawSteps = browser.steps;
+        }
+        else if ("steps" in browser) {
+            return { failure: `${args.relativePath} browser.steps must be a non-empty array.` };
+        }
+    }
+    if (rawSteps.length === 0 && Array.isArray(args.raw.steps)) {
+        rawSteps = args.raw.steps;
+    }
+    const steps = [];
+    for (const [index, rawStep] of rawSteps.entries()) {
+        const parsed = parseBrowserPersonaStep(rawStep, index);
+        if (parsed.failure) {
+            return { failure: `${args.relativePath}: ${parsed.failure}` };
+        }
+        if (parsed.step) {
+            steps.push(parsed.step);
+        }
+    }
+    if (browser !== undefined && steps.length === 0) {
+        return {
+            failure: `${args.relativePath} declared browser steps, but no executable steps were found.`,
+        };
+    }
+    if (steps.length === 0) {
+        return {};
+    }
+    return {
+        journey: {
+            goal,
+            scenarioId,
+            scenarioTitle,
+            source: args.relativePath,
+            sourceDigest: args.sourceDigest,
+            startPath,
+            steps,
+        },
+    };
+}
+function parseBrowserPersonaStep(rawStep, index) {
+    if (!isRecord(rawStep)) {
+        return { failure: `browser step ${index + 1} must be an object.` };
+    }
+    const inlineBrowser = isRecord(rawStep.browser) ? rawStep.browser : undefined;
+    const source = inlineBrowser ?? rawStep;
+    const hasExecutableFields = inlineBrowser !== undefined ||
+        "action" in rawStep ||
+        "selector" in rawStep ||
+        "path" in rawStep ||
+        "expect" in rawStep;
+    if (!hasExecutableFields) {
+        return {};
+    }
+    const action = browserPersonaActionValue(source.action);
+    if (!action) {
+        return { failure: `browser step ${index + 1} has unsupported or missing action.` };
+    }
+    const label = stringValue(rawStep.name) ??
+        stringValue(rawStep.label) ??
+        stringValue(source.label) ??
+        `Step ${index + 1}`;
+    const id = publicSafeToken(stringValue(rawStep.id) ?? stringValue(source.id), `step-${String(index + 1).padStart(2, "0")}-${label}`);
+    const selector = stringValue(source.selector);
+    const pathValue = stringValue(source.path);
+    const value = stringValue(source.value);
+    const expectation = browserStepExpectationValue(source.expect ?? source.expectation);
+    if (action === "fill" && !selector) {
+        return { failure: `${id} fill action requires selector.` };
+    }
+    if (action === "waitForSelector" && !selector) {
+        return { failure: `${id} waitForSelector action requires selector.` };
+    }
+    if ((action === "assertText" || action === "waitForText") && !expectation?.text && !value) {
+        return { failure: `${id} ${action} action requires expect.text or value.` };
+    }
+    return {
+        step: {
+            action,
+            ...(expectation ? { expectation } : {}),
+            id,
+            label,
+            ...(pathValue === undefined ? {} : { path: pathValue }),
+            ...(selector === undefined ? {} : { selector }),
+            ...(value === undefined ? {} : { value }),
+        },
+    };
+}
+function hasInlineBrowserSteps(value) {
+    return Array.isArray(value) && value.some((entry) => isRecord(entry) && isRecord(entry.browser));
+}
+function browserPersonaActionValue(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[-_\s]+/g, "");
+    if (normalized === "goto" || normalized === "open" || normalized === "navigate")
+        return "goto";
+    if (normalized === "click" || normalized === "press")
+        return "click";
+    if (normalized === "fill" || normalized === "type")
+        return "fill";
+    if (normalized === "asserttext" || normalized === "expecttext")
+        return "assertText";
+    if (normalized === "waitfortext")
+        return "waitForText";
+    if (normalized === "waitforselector")
+        return "waitForSelector";
+    return null;
+}
+function browserStepExpectationValue(value) {
+    if (typeof value === "string" && value.trim()) {
+        return { text: value.trim() };
+    }
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const text = stringValue(value.text);
+    const selectorVisible = stringValue(value.selectorVisible) ?? stringValue(value.selector_visible);
+    const urlIncludes = stringValue(value.urlIncludes) ?? stringValue(value.url_includes);
+    const stateChanged = booleanValue(value.stateChanged) ?? booleanValue(value.state_changed);
+    const expectation = {
+        ...(selectorVisible === undefined ? {} : { selectorVisible }),
+        ...(stateChanged === undefined ? {} : { stateChanged }),
+        ...(text === undefined ? {} : { text }),
+        ...(urlIncludes === undefined ? {} : { urlIncludes }),
+    };
+    return Object.keys(expectation).length === 0 ? undefined : expectation;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function publicSafeToken(value, fallback) {
+    const candidate = (value ?? fallback)
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+    return candidate || fallback;
+}

package/dist/actors/scripted-browser/steps.d.ts

@@ -0,0 +1,60 @@
+import { type PreparedOutputRoot } from "../../run/contained-output.js";
+import { type BrowserPersonaJourney, type BrowserPersonaStepCapture, type BrowserPersonaStepManifest, type BrowserSurface, type ScriptedBrowserEvidenceUrlPolicy, type ScriptedPageLike } from "./types.js";
+export declare function executeBrowserPersonaStep(args: {
+    absoluteArtifactRoot: PreparedOutputRoot;
+    appUrl: string;
+    browserJourney: BrowserPersonaJourney;
+    page: ScriptedPageLike;
+    step: BrowserPersonaStepManifest;
+    surface: BrowserSurface;
+    timeoutMs: number;
+    urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
+}): Promise<BrowserPersonaStepCapture>;
+export declare function buildBlockedBrowserPersonaSteps(args: {
+    browserJourney: BrowserPersonaJourney;
+    currentUrl: string;
+    reason: string;
+    surface: BrowserSurface;
+    timestamp: string;
+    urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
+}): BrowserPersonaStepCapture[];
+export declare function screenshotPathForBrowserStep(surface: BrowserSurface, step: BrowserPersonaStepManifest | undefined): string;
+export declare function tracePathForBrowserSurface(surface: BrowserSurface): string;
+/**
+ * Best-effort screenshot of a blocked step. The step is blocked, so its failure is
+ * the evidence; the shot is a bonus. Returns the relative path plus whether the
+ * write actually produced a non-empty file, so the caller only references the path
+ * when the file truly exists (never claim a screenshot that is not there).
+ */
+export declare function captureBlockedStepScreenshot(page: ScriptedPageLike | null, artifactRoot: PreparedOutputRoot, surface: BrowserSurface, step: BrowserPersonaStepManifest): Promise<{
+    screenshotPath: string;
+    written: boolean;
+}>;
+/**
+ * Surface-level screenshot path = the last step that actually wrote one. Returns
+ * undefined when no step wrote a screenshot (a fully blocked capture whose evidence
+ * is the failure itself), so the producer never synthesizes a path to a file it did
+ * not write.
+ */
+export declare function surfaceScreenshotPath(steps: BrowserPersonaStepCapture[]): string | undefined;
+export declare function buildBrowserTrace(args: {
+    appUrl: string;
+    browserCommand: string;
+    browserJourney: BrowserPersonaJourney;
+    capturedAt: string;
+    durationMs: number;
+    httpStatus?: number;
+    ok: boolean;
+    reason: string;
+    screenshotPath?: string;
+    steps: BrowserPersonaStepCapture[];
+    surface: BrowserSurface;
+}): Record<string, unknown>;
+export declare function sanitizeBrowserEvidenceUrl(value: string, urlPolicy?: ScriptedBrowserEvidenceUrlPolicy): string;
+export declare function probeAppUrl(appUrl: string, timeoutMs: number): Promise<{
+    ok: boolean;
+    reason: string;
+    status?: number;
+}>;
+export declare function normalizeLocalAppUrl(value: string): string | null;
+export declare function compactBrowserError(error: unknown): string;

package/dist/actors/scripted-browser/steps.js

@@ -0,0 +1,384 @@
+// The scripted browser's step executor: run one journey step on a page, evaluate its expectations,
+// build blocked steps after a failure, capture screenshots, and turn the steps into the native
+// browser trace. Evidence URLs pass through the run's URL policy before they are recorded.
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { assertScreenshotEvidence, stripPngMetadataChunks } from "../../evidence/image.js";
+import { digestText, redactToSecretLabel } from "../../evidence/redaction.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
+export async function executeBrowserPersonaStep(args) {
+    const started = Date.now();
+    const urlPolicy = args.urlPolicy ?? LOOPBACK_EVIDENCE_URL_POLICY;
+    const beforeState = await browserPersonaPageState(args.page, urlPolicy);
+    const stepTimeoutMs = Math.min(args.timeoutMs, 8_000);
+    if (args.step.action === "goto") {
+        await args.page.goto(resolveBrowserStepUrlForPolicy(args.appUrl, args.step.path ?? args.browserJourney.startPath, urlPolicy), {
+            waitUntil: "domcontentloaded",
+            timeout: args.timeoutMs,
+        });
+    }
+    else if (args.step.action === "fill") {
+        if (!args.step.selector) {
+            throw new Error(`${args.step.id} fill step is missing selector`);
+        }
+        await args.page
+            .locator(args.step.selector)
+            .first()
+            .fill(args.step.value ?? "synthetic.user@example.test", {
+            timeout: stepTimeoutMs,
+        });
+    }
+    else if (args.step.action === "click") {
+        let target = args.step.selector
+            ? args.page.locator(args.step.selector).first()
+            : args.page
+                .locator("button, input[type='submit'], input[type='button'], [role='button']")
+                .first();
+        if (!args.step.selector) {
+            const textInput = args.page
+                .locator("input:not([type='hidden']):not([type='submit']):not([type='button']), textarea")
+                .first();
+            if ((await textInput.count()) > 0) {
+                await textInput.fill(args.step.value ?? "synthetic.user@example.test", {
+                    timeout: stepTimeoutMs,
+                });
+            }
+        }
+        if ((await target.count()) === 0) {
+            throw new Error(`${args.step.id} click step found no target`);
+        }
+        await target.click({ timeout: stepTimeoutMs });
+        await args.page.waitForTimeout(300);
+    }
+    else if (args.step.action === "assertText" || args.step.action === "waitForText") {
+        const expectedText = args.step.expectation?.text ?? args.step.value;
+        if (!expectedText) {
+            throw new Error(`${args.step.id} text assertion step is missing expected text`);
+        }
+        await waitForPageText(args.page, expectedText, stepTimeoutMs);
+    }
+    else if (args.step.action === "waitForSelector") {
+        if (!args.step.selector) {
+            throw new Error(`${args.step.id} selector wait step is missing selector`);
+        }
+        await args.page
+            .locator(args.step.selector)
+            .first()
+            .waitFor({ state: "visible", timeout: stepTimeoutMs });
+    }
+    else {
+        const exhaustive = args.step.action;
+        throw new Error(`Unsupported browser persona action: ${String(exhaustive)}`);
+    }
+    const afterState = await browserPersonaPageState(args.page, urlPolicy);
+    const screenshotPath = screenshotPathForBrowserStep(args.surface, args.step);
+    await prepareContainedOutputFile(args.absoluteArtifactRoot, screenshotPath);
+    const screenshotBytes = await captureScriptedPageScreenshot(args.page);
+    assertScreenshotEvidence(screenshotPath, screenshotBytes);
+    await writeContainedOutputFile(args.absoluteArtifactRoot, screenshotPath, screenshotBytes);
+    const assertions = await evaluateBrowserStepExpectations({
+        afterState,
+        beforeState,
+        page: args.page,
+        step: args.step,
+        timeoutMs: stepTimeoutMs,
+    });
+    const blockedAssertion = assertions.find((assertion) => assertion.status !== "passed");
+    return {
+        action: args.step.action,
+        ...(assertions.length === 0 ? {} : { assertions }),
+        completedAt: new Date().toISOString(),
+        durationMs: Date.now() - started,
+        id: args.step.id,
+        label: args.step.label,
+        reason: blockedAssertion?.reason ?? `${args.step.action} completed for ${args.step.label}.`,
+        screenshotPath,
+        status: blockedAssertion ? "blocked" : "passed",
+        url: sanitizeBrowserEvidenceUrl(args.page.url(), urlPolicy),
+    };
+}
+async function evaluateBrowserStepExpectations(args) {
+    const assertions = [];
+    const expectation = args.step.expectation;
+    if (!expectation) {
+        return assertions;
+    }
+    if (expectation.stateChanged === true) {
+        const changed = args.beforeState.url !== args.afterState.url ||
+            args.beforeState.bodyDigest !== args.afterState.bodyDigest;
+        assertions.push({
+            id: "state-changed",
+            reason: changed ? "Visible page state changed." : "Visible page state did not change.",
+            status: changed ? "passed" : "blocked",
+        });
+    }
+    if (expectation.text) {
+        assertions.push(await pageTextAssertion(args.page, expectation.text, args.timeoutMs));
+    }
+    if (expectation.selectorVisible) {
+        const visible = await args.page
+            .locator(expectation.selectorVisible)
+            .first()
+            .isVisible({ timeout: args.timeoutMs })
+            .catch(() => false);
+        assertions.push({
+            id: "selector-visible",
+            reason: visible ? "Expected selector was visible." : "Expected selector was not visible.",
+            status: visible ? "passed" : "blocked",
+        });
+    }
+    if (expectation.urlIncludes) {
+        const includes = args.afterState.url.includes(expectation.urlIncludes);
+        assertions.push({
+            id: "url-includes",
+            reason: includes
+                ? "URL included expected public-safe substring."
+                : "URL did not include expected public-safe substring.",
+            status: includes ? "passed" : "blocked",
+        });
+    }
+    return assertions;
+}
+async function pageTextAssertion(page, expectedText, timeoutMs) {
+    const passed = await waitForPageText(page, expectedText, timeoutMs)
+        .then(() => true)
+        .catch(() => false);
+    return {
+        id: "text-present",
+        reason: passed ? "Expected text was present." : "Expected text was not present.",
+        status: passed ? "passed" : "blocked",
+    };
+}
+async function waitForPageText(page, expectedText, timeoutMs) {
+    // Playwright evaluates a string predicate as an expression and never calls it, so a
+    // function-shaped string resolves at once to a truthy function. The needle is inlined instead.
+    await page.waitForFunction(`document.body?.innerText.includes(${JSON.stringify(expectedText)}) === true`, undefined, { timeout: timeoutMs });
+}
+export function buildBlockedBrowserPersonaSteps(args) {
+    // The journey never ran, so no screenshot was written for these steps. The
+    // failure IS the evidence: keep the blocked status + reason, but omit the
+    // screenshot reference so the bundle never claims an artifact that does not
+    // exist (otherwise verify's missingLocalEvidenceArtifacts fails closed on
+    // evidence that was never meant to exist).
+    return args.browserJourney.steps.map((step) => ({
+        action: step.action,
+        completedAt: args.timestamp,
+        durationMs: 0,
+        id: step.id,
+        label: step.label,
+        reason: args.reason,
+        status: "blocked",
+        url: sanitizeBrowserEvidenceUrl(args.currentUrl, args.urlPolicy),
+    }));
+}
+export function screenshotPathForBrowserStep(surface, step) {
+    assertSafeOutputPathSegment(surface.id, "Browser surface id");
+    if (step) {
+        assertSafeOutputPathSegment(step.id, "Browser journey step id");
+    }
+    return path.join("screenshots", `${surface.id}-${step?.id ?? "step"}.png`);
+}
+export function tracePathForBrowserSurface(surface) {
+    assertSafeOutputPathSegment(surface.id, "Browser surface id");
+    return path.join("traces", `${surface.id}.json`);
+}
+/**
+ * Best-effort screenshot of a blocked step. The step is blocked, so its failure is
+ * the evidence; the shot is a bonus. Returns the relative path plus whether the
+ * write actually produced a non-empty file, so the caller only references the path
+ * when the file truly exists (never claim a screenshot that is not there).
+ */
+export async function captureBlockedStepScreenshot(page, artifactRoot, surface, step) {
+    const screenshotPath = screenshotPathForBrowserStep(surface, step);
+    await prepareContainedOutputFile(artifactRoot, screenshotPath);
+    if (!page) {
+        return { screenshotPath, written: false };
+    }
+    try {
+        const screenshotBytes = await captureScriptedPageScreenshot(page);
+        assertScreenshotEvidence(screenshotPath, screenshotBytes);
+        await writeContainedOutputFile(artifactRoot, screenshotPath, screenshotBytes);
+        return { screenshotPath, written: true };
+    }
+    catch {
+        return { screenshotPath, written: false };
+    }
+}
+/**
+ * Surface-level screenshot path = the last step that actually wrote one. Returns
+ * undefined when no step wrote a screenshot (a fully blocked capture whose evidence
+ * is the failure itself), so the producer never synthesizes a path to a file it did
+ * not write.
+ */
+export function surfaceScreenshotPath(steps) {
+    for (let index = steps.length - 1; index >= 0; index -= 1) {
+        const candidate = steps[index]?.screenshotPath?.trim();
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function resolveBrowserStepUrlForPolicy(appUrl, value, urlPolicy = LOOPBACK_EVIDENCE_URL_POLICY) {
+    const url = new URL(value?.trim() || "", appUrl);
+    if (urlPolicy.kind === "provisioned-subject") {
+        const subjectOrigin = new URL(appUrl).origin;
+        if (url.origin !== subjectOrigin) {
+            throw new Error("browser step URL must resolve within the provisioned subject origin");
+        }
+        return url.toString();
+    }
+    const normalized = normalizeLocalAppUrl(url.toString());
+    if (!normalized) {
+        throw new Error("browser step URL must resolve to a loopback HTTP URL");
+    }
+    return normalized;
+}
+async function browserPersonaPageState(page, urlPolicy = LOOPBACK_EVIDENCE_URL_POLICY) {
+    const bodyText = await page.evaluate("document.body ? document.body.innerText : ''");
+    return {
+        bodyDigest: digestText(bodyText.slice(0, 4_000)),
+        url: sanitizeBrowserEvidenceUrl(page.url(), urlPolicy),
+    };
+}
+export function buildBrowserTrace(args) {
+    return {
+        schema: "humanish.browser-persona-trace.v1",
+        capturedAt: args.capturedAt,
+        appUrl: args.appUrl,
+        browserCommand: args.browserCommand,
+        durationMs: args.durationMs,
+        ...(args.httpStatus === undefined ? {} : { httpStatus: args.httpStatus }),
+        ok: args.ok,
+        reason: args.reason,
+        scenario: {
+            id: args.browserJourney.scenarioId,
+            title: args.browserJourney.scenarioTitle,
+            source: args.browserJourney.source,
+            sourceDigest: args.browserJourney.sourceDigest,
+            stepCount: args.browserJourney.steps.length,
+        },
+        ...(args.screenshotPath === undefined ? {} : { screenshotPath: args.screenshotPath }),
+        steps: args.steps,
+        surface: args.surface,
+        redaction: "passed",
+    };
+}
+function sanitizeLoopbackUrl(value) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.hostname === "localhost" ||
+            parsed.hostname === "127.0.0.1" ||
+            parsed.hostname === "::1") {
+            parsed.username = "";
+            parsed.password = "";
+            parsed.search = parsed.search ? "?[redacted-query]" : "";
+            parsed.hash = parsed.hash ? "#[redacted-hash]" : "";
+            return parsed.toString();
+        }
+    }
+    catch { }
+    return "[redacted-url]";
+}
+export function sanitizeBrowserEvidenceUrl(value, urlPolicy = LOOPBACK_EVIDENCE_URL_POLICY) {
+    if (urlPolicy.kind === "loopback") {
+        return sanitizeLoopbackUrl(value);
+    }
+    const evidenceOrigin = urlPolicy.evidenceOrigin.trim() || "[provisioned-subject]";
+    try {
+        const parsed = new URL(value);
+        const pathname = parsed.pathname || "/";
+        const search = parsed.search ? "?[redacted-query]" : "";
+        const hash = parsed.hash ? "#[redacted-hash]" : "";
+        return `${evidenceOrigin}${pathname}${search}${hash}`;
+    }
+    catch {
+        return evidenceOrigin;
+    }
+}
+export async function probeAppUrl(appUrl, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(appUrl, {
+            signal: controller.signal,
+        });
+        return {
+            ok: response.status < 500,
+            reason: `HTTP ${response.status}`,
+            status: response.status,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: compactBrowserError(error),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function normalizeLocalAppUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return null;
+        }
+        if (!["127.0.0.1", "localhost", "::1"].includes(url.hostname)) {
+            return null;
+        }
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+export function compactBrowserError(error) {
+    if (error instanceof Error) {
+        return redactSensitiveText(error.message).replace(/\s+/g, " ").slice(0, 240);
+    }
+    return redactSensitiveText(String(error)).replace(/\s+/g, " ").slice(0, 240);
+}
+function browserScreenshotBytes(value) {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value);
+    }
+    throw new Error("Browser screenshot did not return image bytes.");
+}
+async function captureScriptedPageScreenshot(page) {
+    const stagingPath = await mkdtemp(path.join(os.tmpdir(), "humanish-browser-shot-"));
+    const stagingRoot = await prepareSelectedOutputDirectory(path.dirname(stagingPath), stagingPath);
+    try {
+        const returned = await page.screenshot({
+            path: path.join(stagingRoot.physicalPath, "capture.png"),
+            fullPage: true,
+        });
+        // Evidence holds image data only; see stripPngMetadataChunks.
+        if (Buffer.isBuffer(returned) || returned instanceof Uint8Array) {
+            return stripPngMetadataChunks(browserScreenshotBytes(returned));
+        }
+        const stagedBytes = await readContainedRegularFile(stagingRoot, "capture.png");
+        if (!stagedBytes) {
+            throw new Error("Browser screenshot did not return bytes or write a single-link staging file.");
+        }
+        return stripPngMetadataChunks(stagedBytes);
+    }
+    finally {
+        await assertPreparedSelectedOutputDirectory(stagingRoot)
+            .then(() => rm(stagingRoot.physicalPath, { force: true, recursive: true }))
+            .catch(() => undefined);
+    }
+}
+function redactSensitiveText(text) {
+    return redactToSecretLabel(text);
+}