skeptic-cli 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1252 @@
+import { Command } from 'commander';
+import { Page, Locator } from 'playwright';
+import * as _playwright_test from '@playwright/test';
+import { z } from 'zod';
+
+type Engine = "chromium" | "firefox" | "webkit";
+
+interface ConnectDaemonOptions {
+    engine: Engine;
+    headed: boolean;
+    cliVersion: string;
+    /** Override the auto-spawn behavior (tests use this to assert no-spawn paths). */
+    autoSpawn?: boolean;
+    /** Override max wait for socket-ready, ms. */
+    spawnTimeoutMs?: number;
+    /** Override the daemon idle timeout in seconds. Forwarded to the spawned daemon. */
+    idleTimeoutSeconds?: number;
+}
+
+/**
+ * Single source of truth for whether a given argv invokes a Commander command
+ * that needs a browser. Used by the auto-spawn discipline (plan §B10 invariant
+ * 8) — only `run` / `tui` (without `--list`) and `inspect` should auto-launch
+ * the daemon. Every other command (init/audit/comment/cookies/browsers
+ * install/run --list/mcp/acp/add/generate/help) returns false.
+ *
+ * Also returns false when `--no-daemon` is present — that flag is the
+ * opt-out. The caller is responsible for re-checking this predicate before
+ * any pre-warm so the dead-code regression caught in the B10 audit doesn't
+ * recur.
+ *
+ * Argv shape is whatever `process.argv` would look like — typically
+ * `["node", "skeptic", "<cmd>", ...]` or just `["<cmd>", ...]`.
+ */
+declare const commandUsesBrowser: (argv: readonly string[]) => boolean;
+interface PrewarmOptions {
+    /** Engine the upcoming workers / inspect will request. */
+    engine: ConnectDaemonOptions["engine"];
+    /** Headed flag the upcoming workers / inspect will request. */
+    headed: boolean;
+    /** CLI version for the handshake. */
+    cliVersion: string;
+    /** When true, the caller already ran `--no-daemon` — skip pre-warm. */
+    noDaemon: boolean;
+    /** Forwarded to the spawned daemon. */
+    idleTimeoutSeconds?: number;
+}
+/**
+ * Main-process pre-warm. When the predicate matches AND `--no-daemon` is
+ * absent, spawn the daemon now (before any workers fork) so subsequent
+ * worker-side `connectDaemon` calls hit the fast path (`isSocketConnectable`
+ * returns true and no spawn happens inside the worker).
+ *
+ * Returns true when the daemon is alive (or was made alive), false when we
+ * skipped the pre-warm. On spawn failure the function logs a warning and
+ * returns false — workers will then fall back to fresh launches per the
+ * `--no-daemon` semantics, so the run still proceeds.
+ */
+declare const prewarmDaemonIfNeeded: (argv: readonly string[], opts: PrewarmOptions) => Promise<boolean>;
+
+type AIProvider = "gemini" | "openai" | "anthropic";
+/**
+ * Result of an AI call. `retryCount` is the number of transient retries that
+ * `withRetry` performed before success; 0 means the first attempt worked.
+ * Surfacing this lets step handlers add a `StepResult.warnings` entry like
+ * "AI retried 2× before success" so users can see when CI was rescued.
+ */
+interface AIResult {
+    text: string;
+    retryCount: number;
+}
+interface AIClient {
+    readonly provider: AIProvider;
+    analyzeImage(imageBuffer: Buffer, prompt: string, temperature?: number): Promise<AIResult>;
+    generateText(prompt: string, system?: string, temperature?: number): Promise<AIResult>;
+}
+
+/**
+ * ARIA snapshot-ref entry — one record per minted ref.
+ *
+ * Refs are sequential identifiers (e1, e2, …) produced by Playwright's
+ * `Locator.ariaSnapshot({mode:"ai"})` plus a parallel cursor-interactive pass
+ * (ported from agent-browser, Apache 2.0).
+ *
+ * Resolution is `kind`-discriminated:
+ *   - `aria` → `getByRole(role, { name, exact: true }).nth(nth)` against `scopeSelector`.
+ *   - `cursor-interactive` → `resolveElement(page, selectorHint)` (the existing
+ *     skeptic-grammar resolver: `testid=…` / `role=…` / `css=…` / raw text).
+ *
+ * `selectorHint` is the **stable, cross-process artifact** an agent copies into a
+ * `*.spec.ts` file. `@eN` refs are volatile — only valid inside one test run after a
+ * `snapshot(page)` call.
+ *
+ * `matchCountAtSnapshot` records the size of the (role, name) candidate group at
+ * capture time. The resolver re-counts the live group; if it changed AND the
+ * recorded `nth === 0`, we emit a warning that an insertion may have silently
+ * retargeted the ref.
+ */
+type AriaRefKind = "aria" | "cursor-interactive";
+interface AriaRefEntry {
+    ref: string;
+    kind: AriaRefKind;
+    role: string;
+    name: string;
+    nth: number;
+    scopeSelector: string;
+    /** Optional stable selector hint (skeptic grammar). Required for cursor-interactive. */
+    selectorHint?: string;
+    /** Optional href for link refs — extracted post-snapshot, first 50 link refs. */
+    href?: string;
+    /** Number of (role, name) candidates at snapshot time — used by the resolver
+     *  to surface silent insertion-retargeting via a `[aria-ref] eN silently retargeted` log. */
+    matchCountAtSnapshot: number;
+}
+
+/**
+ * Configuration for the visual-settle helper used before screenshots and (optionally) before
+ * video finalization. The helper is a no-op fast-path when `enabled` is false — keeps the
+ * non-observability default zero-cost.
+ */
+interface VisualSettleConfig {
+    enabled: boolean;
+    /** Wait for `networkidle` with this ceiling (ms). 0 disables the network wait. */
+    networkIdleMs: number;
+    /** Number of double-RAF cycles to await. 0 disables. The single most effective settle
+     *  for canvas / WebGL preloaders in practice (most clear by the second RAF). */
+    animationFrames: number;
+    /** Optional pixel-stability poll budget (ms). 0 disables; the cost is one extra
+     *  centred screenshot per poll iteration plus a CRC32 hash. */
+    pixelStableMs: number;
+    /** Overall hard ceiling (ms). Wraps the whole helper in a Node-side Promise.race so a
+     *  misbehaving page can't blow the step's hardTimeout. */
+    hardCeilingMs: number;
+}
+
+interface StepDiagnostic {
+    kind: "blank-screenshot" | "settle-timeout" | "path-rejected" | "auto-a11y-skipped" | string;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Per-test runtime config for the screenshot, settle, and blank-frame pipeline.
+ * The engine resolves it once and freezes it onto `ExecutionContext.artifactConfig`.
+ */
+interface ArtifactRuntimeConfig {
+    fullPageScreenshots: boolean;
+    visualSettle: VisualSettleConfig;
+    blankFrameDetection: "off" | "warn" | "fail";
+    writeSidecars: boolean;
+}
+
+declare class ExecutionContext {
+    readonly page: Page;
+    readonly screenshots: string[];
+    private baseUrl;
+    lastElement: Locator | null;
+    readonly testDir: string;
+    readonly sourceDir: string;
+    readonly aiClient?: AIClient;
+    readonly aiProvider?: AIProvider;
+    readonly defaultTimeout: number;
+    activeTimeout: number;
+    readonly collectors: Map<CollectorName, Collector>;
+    /** Per-test artifact runtime config — set by the engine when constructing the context.
+     *  Read by the screenshot handler and by the engine's pre-video-finalize settle hook. */
+    readonly artifactConfig: ArtifactRuntimeConfig;
+    /**
+     * ARIA snapshot ref registry — populated by the `ariaSnapshot` step, consumed by
+     * `resolveSelectorArg`'s `@`-prefix branch. Each `ariaSnapshot` step clears and refills the map;
+     * refs do not persist across snapshots (matches Expect's ephemeral-ref design).
+     */
+    readonly ariaRefs: Map<string, AriaRefEntry>;
+    /**
+     * Last captured snapshot YAML (verbatim Playwright output). In-memory only — never logged or
+     * serialized into StepResult, since snapshots may include user-typed PII. Used by error messages
+     * to indicate whether a snapshot has run yet.
+     */
+    ariaSnapshotYaml: string | null;
+    /**
+     * Set when a hardTimeout fires. Fixture actions check this before each await
+     * and short-circuit unless `inTeardown` is set.
+     */
+    abortReason: string | null;
+    /**
+     * Set while running teardown hooks so cleanup can still execute after an
+     * aborted test body.
+     */
+    inTeardown: boolean;
+    constructor(page: Page, baseUrl: string, testDir?: string, sourceDir?: string, aiClient?: AIClient, aiProvider?: AIProvider, defaultTimeout?: number, collectors?: Collector[], artifactConfig?: ArtifactRuntimeConfig);
+    resolveUrl(path: string): string;
+    addScreenshot(path: string): void;
+}
+
+type CollectorName = "performance" | "network" | "accessibility" | "console";
+interface Collector {
+    readonly name: CollectorName;
+    attach(page: Page, ctx: ExecutionContext): Promise<void>;
+    snapshot(): Promise<unknown>;
+    detach(): Promise<void>;
+}
+interface LongAnimationFrame {
+    startTime: number;
+    duration: number;
+    blockingDuration: number;
+    scripts: Array<{
+        invoker: string;
+        sourceURL: string;
+        sourceFunctionName: string;
+        duration: number;
+        /**
+         * Per-script forced style/layout time (ms). Per Chromium's LoAF spec this lives on
+         * `PerformanceScriptTiming` entries (script-level), not on the frame itself.
+         * Frame-level "forced layout" rendering is computed as
+         * `Math.max(...scripts.map(s => s.forcedStyleAndLayoutDuration))`.
+         */
+        forcedStyleAndLayoutDuration: number;
+    }>;
+}
+interface NavigationTiming {
+    /** ms from navigation start to first byte. */
+    ttfb: number | null;
+    /** ms from navigation start to DOMContentLoadedEventEnd. */
+    domContentLoaded: number | null;
+    /** ms from navigation start to loadEventEnd. */
+    loadComplete: number | null;
+    /**
+     * `PerformanceServerTiming` entries from the navigation response, when the origin
+     * sent a `Server-Timing` header. Most pages don't emit this; rendered only when present.
+     */
+    serverTiming?: Array<{
+        name: string;
+        duration?: number;
+        description?: string;
+    }>;
+}
+interface ResourceTiming {
+    name: string;
+    initiatorType: string;
+    /** ms — `responseEnd - startTime`. */
+    duration: number;
+    /** Bytes transferred over the wire (compressed). 0 when the entry was served from cache. */
+    transferSize: number;
+    encodedBodySize: number;
+    decodedBodySize: number;
+}
+interface PerformanceSnapshot {
+    fcp: number | null;
+    lcp: number | null;
+    cls: number | null;
+    inp: number | null;
+    ttfb: number | null;
+    longAnimationFrames: LongAnimationFrame[];
+    /** Best-effort navigation-timing read at snapshot. */
+    navigationTiming?: NavigationTiming;
+    /** PerformanceResourceTiming entries, captured once at snapshot. Optional. */
+    resources?: ResourceTiming[];
+}
+interface ConsoleMessage {
+    /** Playwright console message type — log/warning/error/info/debug/trace etc. */
+    type: string;
+    /** Post-redacted text, truncated to 4 KB. */
+    text: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    timestamp: number;
+}
+interface ConsoleSnapshot {
+    messages: ConsoleMessage[];
+    summary: {
+        total: number;
+        errorCount: number;
+        warningCount: number;
+        infoCount: number;
+        /** True when redaction was disabled via config (report should show a banner). */
+        redactionDisabled: boolean;
+    };
+}
+interface NetworkRequest {
+    url: string;
+    method: string;
+    status?: number;
+    resourceType: string;
+    duration?: number;
+    timestamp: number;
+    failure?: string;
+    frameUrl?: string;
+}
+interface NetworkSnapshot {
+    requests: NetworkRequest[];
+    issues: {
+        failedRequests: Array<{
+            url: string;
+            method: string;
+            status: number;
+        }>;
+        networkFailures: Array<{
+            url: string;
+            method: string;
+            reason: string;
+        }>;
+        duplicates: Array<{
+            url: string;
+            method: string;
+            count: number;
+            windowMs: number;
+        }>;
+        mixedContent: string[];
+        corsErrors: Array<{
+            url: string;
+            method: string;
+            reason: string;
+        }>;
+    };
+    summary?: {
+        requestCount: number;
+        failedRequestCount: number;
+        networkFailureCount: number;
+        duplicateGroupCount: number;
+        mixedContentCount: number;
+        corsErrorCount: number;
+        issueCount: number;
+        captureLimit: number;
+        truncated: boolean;
+        resourceTypes: Record<string, number>;
+        methods: Record<string, number>;
+        statusCodes: Record<string, number>;
+    };
+}
+interface AccessibilityViolation {
+    ruleId: string;
+    impact: "critical" | "serious" | "moderate" | "minor";
+    engine: "axe" | "equal-access";
+    help: string;
+    helpUrl?: string;
+    nodes: Array<{
+        target: string[];
+        html: string;
+        failureSummary?: string;
+    }>;
+}
+interface AccessibilitySnapshot {
+    violations: AccessibilityViolation[];
+    summary: {
+        violations: number;
+        passes: number;
+        incomplete: number;
+        dualEngine: boolean;
+        /**
+         * Engines the audit was configured to run. Always includes "axe"; includes
+         * "equal-access" when dualEngine is true and the optional peer is installed.
+         */
+        enginesRequested?: Array<"axe" | "equal-access">;
+        /**
+         * Engines whose audit threw or otherwise failed to produce results.
+         */
+        enginesErrored?: Array<{
+            engine: "axe" | "equal-access";
+            reason: string;
+        }>;
+    };
+    standard: string;
+}
+
+interface AnnotationBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+interface ScreenshotOptions {
+    fullPage?: boolean;
+    /** When true, inject numbered badges over interactive refs before capture and
+     *  attach an `annotation-map` diagnostic to the result. */
+    annotate?: boolean;
+    /** CSS selector scoping the annotated set. Defaults to `body`. */
+    annotateScope?: string;
+}
+interface AnnotationMapEntry {
+    label: number;
+    ref: string;
+    role: string;
+    boundingBox: AnnotationBox;
+    selectorHint?: string;
+}
+interface ScreenshotResult {
+    path: string;
+    diagnostics: StepDiagnostic[];
+    /** Populated only when `opts.annotate === true`. Contains one entry per labeled
+     *  badge — refs whose bbox could not be resolved are skipped (off-screen / detached). */
+    annotations?: AnnotationMapEntry[];
+}
+
+interface SnapshotOptions {
+    /** Match `agent-browser snapshot -i` — only nodes with refs. */
+    interactive?: boolean;
+    /** Match `agent-browser snapshot -c` — interactive + minimal ancestors. */
+    compact?: boolean;
+    /** Scope to a CSS selector. Defaults to `body` for full-page snapshots. */
+    selector?: string;
+    /** Emit "N items hidden above/below" markers. Default true on the public API. */
+    viewportAware?: boolean;
+    /** Run the cursor-interactive heuristic. Default true on the public API. */
+    includeCursorInteractive?: boolean;
+}
+interface ByRoleOptions {
+    name?: string | RegExp;
+    hrefIncludes?: string;
+    /** When duplicates exist, pick this match (default 0). */
+    index?: number;
+}
+interface SnapshotTree {
+    /** Rendered YAML matching agent-browser's format (full / interactive / compact). */
+    yaml: string;
+    /** Raw Playwright YAML before rendering — kept for diagnostics. */
+    rawYaml: string;
+    refs: Map<string, AriaRefEntry>;
+    stats: SnapshotStats;
+    byRef(ref: string): Locator | Promise<Locator>;
+    byRole(role: string, opts?: ByRoleOptions): Locator;
+    byText(text: string | RegExp): Locator;
+    byTestId(id: string): Locator;
+    cursorInteractiveCount: number;
+    ariaRefCount: number;
+}
+interface SnapshotStats {
+    /** Rendered YAML line count. Empty output follows Expect parity: one empty line. */
+    lines: number;
+    /** Rendered YAML character count. */
+    characters: number;
+    /** Rough model-token estimate using the common 4 chars/token heuristic. */
+    estimatedTokens: number;
+    /** All refs captured into the registry, including low-signal refs hidden from compact output. */
+    totalRefs: number;
+    /** Unique refs visible in the rendered YAML. */
+    renderedRefs: number;
+    /** Captured action-oriented refs. Cursor-interactive entries count as interactive. */
+    interactiveRefs: number;
+    /** Action-oriented refs visible in the rendered YAML. */
+    renderedInteractiveRefs: number;
+    ariaRefs: number;
+    cursorInteractiveRefs: number;
+}
+
+interface AiAssertOpts {
+    target?: Locator;
+}
+interface AiDefectsOpts extends AiAssertOpts {
+    /** Future hook for severity filtering — wired in B5 along with the AI rewrite. */
+    minSeverity?: "low" | "medium" | "high" | "critical";
+}
+interface AiExtractOpts<T> extends AiAssertOpts {
+    /** Optional Zod-or-similar schema. We accept any object exposing `.parse(value)`. */
+    schema?: {
+        parse: (value: unknown) => T;
+    };
+}
+interface AiFixture {
+    assert(claim: string, opts?: AiAssertOpts): Promise<void>;
+    assertNoDefects(opts?: AiDefectsOpts): Promise<void>;
+    extract<T = string>(query: string, opts?: AiExtractOpts<T>): Promise<T>;
+}
+
+interface PerfThresholds {
+    /** Largest Contentful Paint, e.g. "<2500ms". */
+    lcp?: string;
+    /** Cumulative Layout Shift, e.g. "<0.1". */
+    cls?: string;
+    /** Interaction to Next Paint, e.g. "<200ms". */
+    inp?: string;
+    /** First Contentful Paint, e.g. "<1800ms". */
+    fcp?: string;
+    /** Time to First Byte, e.g. "<800ms". */
+    ttfb?: string;
+}
+interface NetworkAssertOpts {
+    /** URL substrings or regexes that should be ignored. */
+    allow?: Array<string | RegExp>;
+}
+interface ConsoleAssertOpts {
+    allow?: Array<string | RegExp>;
+}
+interface AxeAuditOpts {
+    standard?: "WCAG2A" | "WCAG2AA" | "WCAG21A" | "WCAG21AA" | "WCAG22AA";
+    include?: string[];
+    exclude?: string[];
+    impacts?: Array<"critical" | "serious" | "moderate" | "minor">;
+}
+interface ObservabilityFixture {
+    expectPerformance(thresholds: PerfThresholds): Promise<void>;
+    expectNoNetworkErrors(opts?: NetworkAssertOpts): Promise<void>;
+    expectNoConsoleErrors(opts?: ConsoleAssertOpts): Promise<void>;
+    expectAccessible(opts?: AxeAuditOpts): Promise<void>;
+    snapshot(): Promise<{
+        performance?: PerformanceSnapshot;
+        network?: NetworkSnapshot;
+        console?: ConsoleSnapshot;
+        accessibility?: AccessibilitySnapshot;
+    }>;
+}
+
+interface SkepticFixture {
+    page: Page;
+    ctx: ExecutionContext;
+    /** Wraps a fixture-method body in the abort-aware boundary. Re-checks ctx.abortReason
+     *  before each await, surfaces a clean error after a hard-timeout, and emits a
+     *  `runner:action` marker the runner uses for video/cursor sidechannels. */
+    runAction: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+    snapshot: (target?: Page | Locator, opts?: SnapshotOptions) => Promise<SnapshotTree>;
+    screenshot: (name: string, opts?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    settle: () => Promise<void>;
+    observability: ObservabilityFixture;
+    ai: AiFixture;
+}
+
+interface TestUseOptions {
+    /** Base URL — used by the runner to set the page's default base. Per-test override via `await page.goto(absoluteUrl)`. */
+    url?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Video recording resolution. When set, overrides the default of using the
+     * viewport size for `recordVideo.size`. Page rendering still happens at
+     * viewport dimensions; this only changes the WebM resolution. Precedence
+     * is CLI `--video-size` > `test.use({ videoSize })` > viewport.
+     */
+    videoSize?: {
+        width: number;
+        height: number;
+    };
+    device?: string;
+    cookies?: boolean | {
+        browser?: string;
+    };
+    env?: Record<string, string>;
+    tags?: string[];
+    /** Declarative collector attach. `--observability` overrides this with the full set. */
+    collectors?: CollectorName[];
+    /** Soft per-action default timeout (Playwright `setDefaultTimeout`). */
+    timeout?: number;
+    /** Hard per-test ceiling enforced by the runner via Promise.race + worker.terminate(). */
+    hardTimeout?: number;
+    retries?: number;
+}
+type TestFn = (fixture: SkepticFixture) => Promise<void> | void;
+type HookFn = (fixture: SkepticFixture) => Promise<void> | void;
+interface TestApi {
+    (name: string, fn: TestFn, use?: TestUseOptions): void;
+    skip: (name: string, fn: TestFn, use?: TestUseOptions) => void;
+    only: (name: string, fn: TestFn, use?: TestUseOptions) => void;
+    use: (options: TestUseOptions) => void;
+    beforeEach: (fn: HookFn, use?: TestUseOptions) => void;
+    afterEach: (fn: HookFn, use?: TestUseOptions) => void;
+}
+declare const test: TestApi;
+
+/**
+ * Re-export Playwright's `expect` so test authors get the full matcher catalog
+ * (toHaveURL, toBeVisible, etc.) with one import:
+ *
+ *   import { test, expect } from "skeptic-cli";
+ *
+ * Skeptic-specific matchers — toMatchSnapshot, toBeAccessible — land in B5/B6.
+ * They're defined here so the surface is stable; B5 plugs in the real bodies.
+ */
+declare const expect: _playwright_test.Expect<{}>;
+
+/** Browser engine configuration. */
+declare const BrowserConfigSchema: z.ZodObject<{
+    engine: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+    headless: z.ZodDefault<z.ZodBoolean>;
+    slowMo: z.ZodDefault<z.ZodNumber>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodDefault<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+    device: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    engine: "chromium" | "firefox" | "webkit";
+    headless: boolean;
+    slowMo: number;
+    timeout: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    device?: string | undefined;
+}, {
+    engine?: "chromium" | "firefox" | "webkit" | undefined;
+    headless?: boolean | undefined;
+    slowMo?: number | undefined;
+    timeout?: number | undefined;
+    viewport?: {
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    device?: string | undefined;
+}>;
+/** Auth configuration (cookie extraction). */
+declare const AuthConfigSchema: z.ZodObject<{
+    cookies: z.ZodDefault<z.ZodBoolean>;
+    browsers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    cookies: boolean;
+    browsers: string[];
+}, {
+    cookies?: boolean | undefined;
+    browsers?: string[] | undefined;
+}>;
+/** Execution configuration (retries, parallelism, bail). */
+declare const ExecutionConfigSchema: z.ZodObject<{
+    retries: z.ZodDefault<z.ZodNumber>;
+    bail: z.ZodDefault<z.ZodBoolean>;
+    screenshotOnFailure: z.ZodDefault<z.ZodBoolean>;
+    parallel: z.ZodDefault<z.ZodNumber>;
+    grep: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    retries: number;
+    bail: boolean;
+    screenshotOnFailure: boolean;
+    parallel: number;
+    tags: string[];
+    grep?: string | undefined;
+}, {
+    retries?: number | undefined;
+    bail?: boolean | undefined;
+    screenshotOnFailure?: boolean | undefined;
+    parallel?: number | undefined;
+    grep?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+/** Output configuration (reporters, output dir). */
+declare const OutputConfigSchema: z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+    reporters: z.ZodDefault<z.ZodArray<z.ZodEnum<["console", "html", "json", "junit"]>, "many">>;
+    open: z.ZodDefault<z.ZodBoolean>;
+    verbose: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    dir: string;
+    reporters: ("console" | "html" | "json" | "junit")[];
+    open: boolean;
+    verbose: boolean;
+}, {
+    dir?: string | undefined;
+    reporters?: ("console" | "html" | "json" | "junit")[] | undefined;
+    open?: boolean | undefined;
+    verbose?: boolean | undefined;
+}>;
+/** Safety controls for agent-driven browser work. */
+declare const SafetyConfigSchema: z.ZodObject<{
+    /**
+     * Empty means unrestricted. Entries accept exact hostnames, URLs whose host is
+     * used, "*" for unrestricted, or "*.example.com" for a domain and children.
+     */
+    allowedDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Optional JSON policy file, resolved relative to the working directory:
+     * { "default": "allow"|"deny", "allow": ["browser_open"], "deny": [...] }.
+     */
+    actionPolicy: z.ZodOptional<z.ZodString>;
+    /**
+     * Actions that require interactive confirmation. MCP/browser sessions fail
+     * closed for these because there is no safe prompt channel in stdio tools.
+     */
+    confirmActions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Maximum characters returned inline from agent-facing JSON/text tools. */
+    maxOutputChars: z.ZodDefault<z.ZodNumber>;
+    /** Wrap inline tool output in XML-ish boundaries for prompt-injection hygiene. */
+    contentBoundaries: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    allowedDomains: string[];
+    confirmActions: string[];
+    maxOutputChars: number;
+    contentBoundaries: boolean;
+    actionPolicy?: string | undefined;
+}, {
+    allowedDomains?: string[] | undefined;
+    actionPolicy?: string | undefined;
+    confirmActions?: string[] | undefined;
+    maxOutputChars?: number | undefined;
+    contentBoundaries?: boolean | undefined;
+}>;
+/** AI configuration. */
+declare const AIConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<["gemini", "openai", "anthropic"]>>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    maxRequestsPerMinute: z.ZodDefault<z.ZodNumber>;
+    baseBranch: z.ZodDefault<z.ZodString>;
+    excludePaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    provider: "gemini" | "openai" | "anthropic";
+    maxRequestsPerMinute: number;
+    baseBranch: string;
+    excludePaths: string[];
+    apiKey?: string | undefined;
+    model?: string | undefined;
+}, {
+    provider?: "gemini" | "openai" | "anthropic" | undefined;
+    apiKey?: string | undefined;
+    model?: string | undefined;
+    maxRequestsPerMinute?: number | undefined;
+    baseBranch?: string | undefined;
+    excludePaths?: string[] | undefined;
+}>;
+/** Top-level skeptic.config.yaml schema. */
+declare const skepticConfigSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    tests: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    browser: z.ZodDefault<z.ZodObject<{
+        engine: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+        headless: z.ZodDefault<z.ZodBoolean>;
+        slowMo: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+        viewport: z.ZodDefault<z.ZodObject<{
+            width: z.ZodDefault<z.ZodNumber>;
+            height: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        device: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        engine: "chromium" | "firefox" | "webkit";
+        headless: boolean;
+        slowMo: number;
+        timeout: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        device?: string | undefined;
+    }, {
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        device?: string | undefined;
+    }>>;
+    auth: z.ZodDefault<z.ZodObject<{
+        cookies: z.ZodDefault<z.ZodBoolean>;
+        browsers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        cookies: boolean;
+        browsers: string[];
+    }, {
+        cookies?: boolean | undefined;
+        browsers?: string[] | undefined;
+    }>>;
+    execution: z.ZodDefault<z.ZodObject<{
+        retries: z.ZodDefault<z.ZodNumber>;
+        bail: z.ZodDefault<z.ZodBoolean>;
+        screenshotOnFailure: z.ZodDefault<z.ZodBoolean>;
+        parallel: z.ZodDefault<z.ZodNumber>;
+        grep: z.ZodOptional<z.ZodString>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        retries: number;
+        bail: boolean;
+        screenshotOnFailure: boolean;
+        parallel: number;
+        tags: string[];
+        grep?: string | undefined;
+    }, {
+        retries?: number | undefined;
+        bail?: boolean | undefined;
+        screenshotOnFailure?: boolean | undefined;
+        parallel?: number | undefined;
+        grep?: string | undefined;
+        tags?: string[] | undefined;
+    }>>;
+    output: z.ZodDefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        reporters: z.ZodDefault<z.ZodArray<z.ZodEnum<["console", "html", "json", "junit"]>, "many">>;
+        open: z.ZodDefault<z.ZodBoolean>;
+        verbose: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        reporters: ("console" | "html" | "json" | "junit")[];
+        open: boolean;
+        verbose: boolean;
+    }, {
+        dir?: string | undefined;
+        reporters?: ("console" | "html" | "json" | "junit")[] | undefined;
+        open?: boolean | undefined;
+        verbose?: boolean | undefined;
+    }>>;
+    ai: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<["gemini", "openai", "anthropic"]>>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        maxRequestsPerMinute: z.ZodDefault<z.ZodNumber>;
+        baseBranch: z.ZodDefault<z.ZodString>;
+        excludePaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "gemini" | "openai" | "anthropic";
+        maxRequestsPerMinute: number;
+        baseBranch: string;
+        excludePaths: string[];
+        apiKey?: string | undefined;
+        model?: string | undefined;
+    }, {
+        provider?: "gemini" | "openai" | "anthropic" | undefined;
+        apiKey?: string | undefined;
+        model?: string | undefined;
+        maxRequestsPerMinute?: number | undefined;
+        baseBranch?: string | undefined;
+        excludePaths?: string[] | undefined;
+    }>>;
+    observability: z.ZodDefault<z.ZodObject<{
+        collectors: z.ZodDefault<z.ZodArray<z.ZodEnum<["performance", "network", "accessibility", "console"]>, "many">>;
+        networkCaptureLimit: z.ZodDefault<z.ZodNumber>;
+        duplicateWindowMs: z.ZodDefault<z.ZodNumber>;
+        accessibilityDualEngine: z.ZodDefault<z.ZodBoolean>;
+        accessibilityHtmlSnippetLimit: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Reporter-aware default-on policy. `passive` auto-attaches perf+net+console when an HTML
+         * reporter is active. `full` also auto-attaches accessibility (with auto-audit). `none`
+         * disables the policy entirely. The merge is done in `commands/test.ts` where reporter
+         * formats are in scope; the registry stays reporter-agnostic.
+         */
+        defaultsForReports: z.ZodDefault<z.ZodEnum<["none", "passive", "full"]>>;
+        consoleCaptureLimit: z.ZodDefault<z.ZodNumber>;
+        consoleRedaction: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * When true, the engine fires `AccessibilityCollector.audit()` once per test before
+         * `onTestComplete`. `--observability` flips this on.
+         */
+        autoAccessibilityAudit: z.ZodDefault<z.ZodBoolean>;
+        accessibilityStandard: z.ZodDefault<z.ZodEnum<["WCAG2A", "WCAG2AA", "WCAG21A", "WCAG21AA", "WCAG22AA"]>>;
+        accessibilityImpacts: z.ZodOptional<z.ZodArray<z.ZodEnum<["critical", "serious", "moderate", "minor"]>, "many">>;
+        /**
+         * Per-impact-bucket cap for the `perf-trace.md` Accessibility section. The
+         * full per-test `audit.md` sidecar always lists every rule regardless of
+         * this cap. Default 100 covers common pages without truncation; bump it
+         * higher (or to 0 for "show all in perf-trace.md") for compliance work.
+         */
+        accessibilityMaxRulesPerImpact: z.ZodDefault<z.ZodNumber>;
+        /** Default fullPage for screenshot steps when a step omits the option. */
+        fullPageScreenshots: z.ZodDefault<z.ZodBoolean>;
+        /** Default blank-frame mode for screenshot steps. Per-step overrides win. */
+        blankFrameDetection: z.ZodDefault<z.ZodEnum<["off", "warn", "fail"]>>;
+    }, "strip", z.ZodTypeAny, {
+        collectors: ("console" | "performance" | "network" | "accessibility")[];
+        networkCaptureLimit: number;
+        duplicateWindowMs: number;
+        accessibilityDualEngine: boolean;
+        accessibilityHtmlSnippetLimit: number;
+        defaultsForReports: "none" | "passive" | "full";
+        consoleCaptureLimit: number;
+        consoleRedaction: boolean;
+        autoAccessibilityAudit: boolean;
+        accessibilityStandard: "WCAG2A" | "WCAG2AA" | "WCAG21A" | "WCAG21AA" | "WCAG22AA";
+        accessibilityMaxRulesPerImpact: number;
+        fullPageScreenshots: boolean;
+        blankFrameDetection: "warn" | "off" | "fail";
+        accessibilityImpacts?: ("critical" | "serious" | "moderate" | "minor")[] | undefined;
+    }, {
+        collectors?: ("console" | "performance" | "network" | "accessibility")[] | undefined;
+        networkCaptureLimit?: number | undefined;
+        duplicateWindowMs?: number | undefined;
+        accessibilityDualEngine?: boolean | undefined;
+        accessibilityHtmlSnippetLimit?: number | undefined;
+        defaultsForReports?: "none" | "passive" | "full" | undefined;
+        consoleCaptureLimit?: number | undefined;
+        consoleRedaction?: boolean | undefined;
+        autoAccessibilityAudit?: boolean | undefined;
+        accessibilityStandard?: "WCAG2A" | "WCAG2AA" | "WCAG21A" | "WCAG21AA" | "WCAG22AA" | undefined;
+        accessibilityImpacts?: ("critical" | "serious" | "moderate" | "minor")[] | undefined;
+        accessibilityMaxRulesPerImpact?: number | undefined;
+        fullPageScreenshots?: boolean | undefined;
+        blankFrameDetection?: "warn" | "off" | "fail" | undefined;
+    }>>;
+    safety: z.ZodDefault<z.ZodObject<{
+        /**
+         * Empty means unrestricted. Entries accept exact hostnames, URLs whose host is
+         * used, "*" for unrestricted, or "*.example.com" for a domain and children.
+         */
+        allowedDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Optional JSON policy file, resolved relative to the working directory:
+         * { "default": "allow"|"deny", "allow": ["browser_open"], "deny": [...] }.
+         */
+        actionPolicy: z.ZodOptional<z.ZodString>;
+        /**
+         * Actions that require interactive confirmation. MCP/browser sessions fail
+         * closed for these because there is no safe prompt channel in stdio tools.
+         */
+        confirmActions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Maximum characters returned inline from agent-facing JSON/text tools. */
+        maxOutputChars: z.ZodDefault<z.ZodNumber>;
+        /** Wrap inline tool output in XML-ish boundaries for prompt-injection hygiene. */
+        contentBoundaries: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        allowedDomains: string[];
+        confirmActions: string[];
+        maxOutputChars: number;
+        contentBoundaries: boolean;
+        actionPolicy?: string | undefined;
+    }, {
+        allowedDomains?: string[] | undefined;
+        actionPolicy?: string | undefined;
+        confirmActions?: string[] | undefined;
+        maxOutputChars?: number | undefined;
+        contentBoundaries?: boolean | undefined;
+    }>>;
+    notifications: z.ZodOptional<z.ZodObject<{
+        slack: z.ZodOptional<z.ZodObject<{
+            onSuccess: z.ZodDefault<z.ZodBoolean>;
+            onFailure: z.ZodDefault<z.ZodBoolean>;
+            webhookUrl: z.ZodString;
+            mention: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            webhookUrl: string;
+            mention: string[];
+            onSuccess: boolean;
+            onFailure: boolean;
+        }, {
+            webhookUrl: string;
+            mention?: string[] | undefined;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+        }>>;
+        webhook: z.ZodOptional<z.ZodObject<{
+            onSuccess: z.ZodDefault<z.ZodBoolean>;
+            onFailure: z.ZodDefault<z.ZodBoolean>;
+            url: z.ZodString;
+            headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            onSuccess: boolean;
+            onFailure: boolean;
+            url: string;
+            headers: Record<string, string>;
+        }, {
+            url: string;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+            headers?: Record<string, string> | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        slack?: {
+            webhookUrl: string;
+            mention: string[];
+            onSuccess: boolean;
+            onFailure: boolean;
+        } | undefined;
+        webhook?: {
+            onSuccess: boolean;
+            onFailure: boolean;
+            url: string;
+            headers: Record<string, string>;
+        } | undefined;
+    }, {
+        slack?: {
+            webhookUrl: string;
+            mention?: string[] | undefined;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+        } | undefined;
+        webhook?: {
+            url: string;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+            headers?: Record<string, string> | undefined;
+        } | undefined;
+    }>>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    tests: string | string[];
+    browser: {
+        engine: "chromium" | "firefox" | "webkit";
+        headless: boolean;
+        slowMo: number;
+        timeout: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        device?: string | undefined;
+    };
+    auth: {
+        cookies: boolean;
+        browsers: string[];
+    };
+    execution: {
+        retries: number;
+        bail: boolean;
+        screenshotOnFailure: boolean;
+        parallel: number;
+        tags: string[];
+        grep?: string | undefined;
+    };
+    output: {
+        dir: string;
+        reporters: ("console" | "html" | "json" | "junit")[];
+        open: boolean;
+        verbose: boolean;
+    };
+    ai: {
+        provider: "gemini" | "openai" | "anthropic";
+        maxRequestsPerMinute: number;
+        baseBranch: string;
+        excludePaths: string[];
+        apiKey?: string | undefined;
+        model?: string | undefined;
+    };
+    observability: {
+        collectors: ("console" | "performance" | "network" | "accessibility")[];
+        networkCaptureLimit: number;
+        duplicateWindowMs: number;
+        accessibilityDualEngine: boolean;
+        accessibilityHtmlSnippetLimit: number;
+        defaultsForReports: "none" | "passive" | "full";
+        consoleCaptureLimit: number;
+        consoleRedaction: boolean;
+        autoAccessibilityAudit: boolean;
+        accessibilityStandard: "WCAG2A" | "WCAG2AA" | "WCAG21A" | "WCAG21AA" | "WCAG22AA";
+        accessibilityMaxRulesPerImpact: number;
+        fullPageScreenshots: boolean;
+        blankFrameDetection: "warn" | "off" | "fail";
+        accessibilityImpacts?: ("critical" | "serious" | "moderate" | "minor")[] | undefined;
+    };
+    safety: {
+        allowedDomains: string[];
+        confirmActions: string[];
+        maxOutputChars: number;
+        contentBoundaries: boolean;
+        actionPolicy?: string | undefined;
+    };
+    env: Record<string, string>;
+    url?: string | undefined;
+    notifications?: {
+        slack?: {
+            webhookUrl: string;
+            mention: string[];
+            onSuccess: boolean;
+            onFailure: boolean;
+        } | undefined;
+        webhook?: {
+            onSuccess: boolean;
+            onFailure: boolean;
+            url: string;
+            headers: Record<string, string>;
+        } | undefined;
+    } | undefined;
+}, {
+    url?: string | undefined;
+    tests?: string | string[] | undefined;
+    browser?: {
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        device?: string | undefined;
+    } | undefined;
+    auth?: {
+        cookies?: boolean | undefined;
+        browsers?: string[] | undefined;
+    } | undefined;
+    execution?: {
+        retries?: number | undefined;
+        bail?: boolean | undefined;
+        screenshotOnFailure?: boolean | undefined;
+        parallel?: number | undefined;
+        grep?: string | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    output?: {
+        dir?: string | undefined;
+        reporters?: ("console" | "html" | "json" | "junit")[] | undefined;
+        open?: boolean | undefined;
+        verbose?: boolean | undefined;
+    } | undefined;
+    ai?: {
+        provider?: "gemini" | "openai" | "anthropic" | undefined;
+        apiKey?: string | undefined;
+        model?: string | undefined;
+        maxRequestsPerMinute?: number | undefined;
+        baseBranch?: string | undefined;
+        excludePaths?: string[] | undefined;
+    } | undefined;
+    observability?: {
+        collectors?: ("console" | "performance" | "network" | "accessibility")[] | undefined;
+        networkCaptureLimit?: number | undefined;
+        duplicateWindowMs?: number | undefined;
+        accessibilityDualEngine?: boolean | undefined;
+        accessibilityHtmlSnippetLimit?: number | undefined;
+        defaultsForReports?: "none" | "passive" | "full" | undefined;
+        consoleCaptureLimit?: number | undefined;
+        consoleRedaction?: boolean | undefined;
+        autoAccessibilityAudit?: boolean | undefined;
+        accessibilityStandard?: "WCAG2A" | "WCAG2AA" | "WCAG21A" | "WCAG21AA" | "WCAG22AA" | undefined;
+        accessibilityImpacts?: ("critical" | "serious" | "moderate" | "minor")[] | undefined;
+        accessibilityMaxRulesPerImpact?: number | undefined;
+        fullPageScreenshots?: boolean | undefined;
+        blankFrameDetection?: "warn" | "off" | "fail" | undefined;
+    } | undefined;
+    safety?: {
+        allowedDomains?: string[] | undefined;
+        actionPolicy?: string | undefined;
+        confirmActions?: string[] | undefined;
+        maxOutputChars?: number | undefined;
+        contentBoundaries?: boolean | undefined;
+    } | undefined;
+    notifications?: {
+        slack?: {
+            webhookUrl: string;
+            mention?: string[] | undefined;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+        } | undefined;
+        webhook?: {
+            url: string;
+            onSuccess?: boolean | undefined;
+            onFailure?: boolean | undefined;
+            headers?: Record<string, string> | undefined;
+        } | undefined;
+    } | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+type skepticConfig = z.infer<typeof skepticConfigSchema>;
+type BrowserConfig = z.infer<typeof BrowserConfigSchema>;
+type AuthConfig = z.infer<typeof AuthConfigSchema>;
+type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+type OutputConfig = z.infer<typeof OutputConfigSchema>;
+type AIConfig = z.infer<typeof AIConfigSchema>;
+type SafetyConfig = z.infer<typeof SafetyConfigSchema>;
+
+/**
+ * Device profiles for responsive testing.
+ * Ported from backend/device_profiles.py — Chrome 134 stable user agents.
+ */
+type DeviceCategory = "desktop" | "phone" | "tablet";
+interface DeviceProfile {
+    label: string;
+    category: DeviceCategory;
+    width: number;
+    height: number;
+    dpr: number;
+    userAgent: string | null;
+}
+declare const DEVICE_PROFILES: Record<string, DeviceProfile>;
+/** Look up a device profile by ID, or return undefined. */
+declare function getDeviceProfile(id: string): DeviceProfile | undefined;
+/** List profiles filtered by category. */
+declare function getProfilesByCategory(category: DeviceCategory): Record<string, DeviceProfile>;
+
+/** Detect CI environment, AI agent environment, and interactivity. */
+interface EnvironmentInfo {
+    /** True when running in a known CI provider. */
+    isCI: boolean;
+    /** Name of the detected CI provider, if any. */
+    ciProvider: string | null;
+    /** True when running inside an AI coding agent. */
+    isAgentEnv: boolean;
+    /** Name of the detected agent, if any. */
+    agentName: string | null;
+    /** True when stdin is a TTY (interactive terminal). */
+    isInteractive: boolean;
+}
+declare function detectCI(): EnvironmentInfo;
+
+interface LoadConfigOptions {
+    /** Explicit path to config file (overrides search). */
+    configPath?: string;
+    /** CLI overrides merged on top of file config. */
+    overrides?: Record<string, unknown>;
+    /**
+     * Override the directory from which the upward walk-up starts when no
+     * `configPath` is provided. Defaults to `process.cwd()`.
+     *
+     * Used by long-lived servers (ACP) that load config relative to a session's
+     * working directory without mutating `process.cwd()`. Ignored when
+     * `configPath` is set.
+     */
+    searchCwd?: string;
+}
+/**
+ * Load and validate skeptic.config.yaml.
+ *
+ * Precedence (highest wins):
+ *   1. CLI flags (overrides)
+ *   2. SKEPTIC_* environment variables
+ *   3. Config file values
+ *   4. Schema defaults
+ *
+ * Environment variable interpolation runs on the raw YAML before validation.
+ */
+declare function loadConfig(opts?: LoadConfigOptions): skepticConfig;
+
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+declare function setLogLevel(level: LogLevel): void;
+declare function getLogLevel(): LogLevel;
+declare const logger: {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    success(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /** Print without prefix — for raw output like tables. */
+    raw(...args: unknown[]): void;
+    /** Like raw(), but error-level gated and written to stderr so --quiet still shows it. */
+    errorRaw(...args: unknown[]): void;
+    /** Styled step header, e.g. "Step 1/5 — Navigate to /login" */
+    step(current: number, total: number, label: string): void;
+};
+
+/** Lightweight duration tracker. */
+declare class Timer {
+    private readonly start;
+    constructor();
+    /** Elapsed time in milliseconds. */
+    elapsedMs(): number;
+    /** Human-readable elapsed time, e.g. "1.23s" or "456ms". */
+    format(): string;
+}
+
+/**
+ * Environment variable interpolation for config values.
+ * Supports ${VAR} and ${VAR:-default} syntax.
+ */
+declare function interpolateEnv(value: string): string;
+/** Recursively interpolate all string values in an object. */
+declare function interpolateEnvDeep(obj: unknown): unknown;
+
+declare const program: Command;
+
+export { type AIConfig, type AiAssertOpts, type AiDefectsOpts, type AiExtractOpts, type AiFixture, type AuthConfig, type AxeAuditOpts, type BrowserConfig, type ConsoleAssertOpts, DEVICE_PROFILES, type DeviceCategory, type DeviceProfile, type EnvironmentInfo, type ExecutionConfig, type HookFn, type NetworkAssertOpts, type ObservabilityFixture, type OutputConfig, type PerfThresholds, type SafetyConfig, type ScreenshotOptions, type ScreenshotResult, type SkepticFixture, type SnapshotOptions, type SnapshotTree, type TestFn, type TestUseOptions, Timer, commandUsesBrowser, detectCI, expect, getDeviceProfile, getLogLevel, getProfilesByCategory, interpolateEnv, interpolateEnvDeep, loadConfig, logger, prewarmDaemonIfNeeded, program, setLogLevel, type skepticConfig, test };