@rolepod/uiproof 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,918 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { Page } from 'playwright';
+
+/**
+ * Writes artifacts under `./.rolepod-uiproof/artifacts/{run_id}/` (D-026).
+ *
+ * v0.1 emits two formats: PNG screenshots and a JSON replay bundle. Future
+ * milestones extend the format set (HAR, console log, a11y tree, video).
+ */
+type ReplayStep = Record<string, unknown>;
+type ReplayBundle = {
+    version: 1;
+    run_id: string;
+    recorded_at: string;
+    open: Record<string, unknown>;
+    steps: ReplayStep[];
+    expect: ReplayStep[];
+};
+declare class ArtifactStore {
+    readonly rootDir: string;
+    constructor(opts?: {
+        rootDir?: string;
+    });
+    /** Allocate a fresh run id and ensure its directory exists. */
+    startRun(prefix?: string): Promise<{
+        runId: string;
+        runDir: string;
+    }>;
+    writeScreenshot(runDir: string, buf: Buffer, name: string): Promise<string>;
+    writeReplayBundle(runDir: string, bundle: ReplayBundle, name?: string): Promise<string>;
+    writeReport(runDir: string, name: string, body: string): Promise<string>;
+    writeBytes(runDir: string, name: string, buf: Buffer): Promise<string>;
+    ensureDir(absDir: string): Promise<string>;
+    /** Root for stored visual baselines: `./.rolepod-uiproof/baselines/`. */
+    get baselineDir(): string;
+    private timestampSlug;
+}
+
+declare const bboxSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, z.core.$strip>;
+declare const a11yStateSchema: z.ZodObject<{
+    focused: z.ZodOptional<z.ZodBoolean>;
+    selected: z.ZodOptional<z.ZodBoolean>;
+    expanded: z.ZodOptional<z.ZodBoolean>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type A11yNode = {
+    ref: string;
+    role: string;
+    name?: string;
+    value?: string;
+    state?: z.infer<typeof a11yStateSchema>;
+    bbox?: z.infer<typeof bboxSchema>;
+    children?: A11yNode[];
+};
+declare const browserOpenShape: {
+    readonly platform: z.ZodDefault<z.ZodEnum<{
+        web: "web";
+        ios: "ios";
+        android: "android";
+    }>>;
+    readonly url: z.ZodOptional<z.ZodString>;
+    readonly browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
+    readonly viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    readonly bundle_id: z.ZodOptional<z.ZodString>;
+    readonly device: z.ZodOptional<z.ZodString>;
+    readonly app_package: z.ZodOptional<z.ZodString>;
+    readonly app_activity: z.ZodOptional<z.ZodString>;
+    readonly emulator: z.ZodOptional<z.ZodString>;
+    readonly headless: z.ZodOptional<z.ZodBoolean>;
+    readonly user_agent: z.ZodOptional<z.ZodString>;
+    readonly locale: z.ZodOptional<z.ZodString>;
+};
+declare const browserOpenSchema: z.ZodObject<{
+    platform: z.ZodDefault<z.ZodEnum<{
+        web: "web";
+        ios: "ios";
+        android: "android";
+    }>>;
+    url: z.ZodOptional<z.ZodString>;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    bundle_id: z.ZodOptional<z.ZodString>;
+    device: z.ZodOptional<z.ZodString>;
+    app_package: z.ZodOptional<z.ZodString>;
+    app_activity: z.ZodOptional<z.ZodString>;
+    emulator: z.ZodOptional<z.ZodString>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+    user_agent: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const browserCloseShape: {
+    readonly session_id: z.ZodString;
+};
+declare const browserCloseSchema: z.ZodObject<{
+    session_id: z.ZodString;
+}, z.core.$strip>;
+declare const browserSnapshotShape: {
+    readonly session_id: z.ZodString;
+    readonly mode: z.ZodOptional<z.ZodEnum<{
+        visible: "visible";
+        full: "full";
+    }>>;
+};
+declare const browserSnapshotSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        visible: "visible";
+        full: "full";
+    }>>;
+}, z.core.$strip>;
+declare const browserClickShape: {
+    readonly session_id: z.ZodString;
+    readonly ref: z.ZodString;
+    readonly button: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        middle: "middle";
+    }>>;
+};
+declare const browserClickSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    ref: z.ZodString;
+    button: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        middle: "middle";
+    }>>;
+}, z.core.$strip>;
+declare const browserTypeShape: {
+    readonly session_id: z.ZodString;
+    readonly ref: z.ZodString;
+    readonly text: z.ZodString;
+    readonly clear_first: z.ZodOptional<z.ZodBoolean>;
+};
+declare const browserTypeSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    ref: z.ZodString;
+    text: z.ZodString;
+    clear_first: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const browserKeyShape: {
+    readonly session_id: z.ZodString;
+    readonly key: z.ZodString;
+};
+declare const browserKeySchema: z.ZodObject<{
+    session_id: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strip>;
+declare const browserScrollShape: {
+    readonly session_id: z.ZodString;
+    readonly direction: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        up: "up";
+        down: "down";
+    }>;
+    readonly amount: z.ZodOptional<z.ZodNumber>;
+    readonly ref: z.ZodOptional<z.ZodString>;
+};
+declare const browserScrollSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    direction: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        up: "up";
+        down: "down";
+    }>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const browserWaitForShape: {
+    readonly session_id: z.ZodString;
+    readonly condition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text_visible">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ref_exists">;
+        query: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url_matches">;
+        pattern: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"idle">;
+        ms: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    readonly timeout_ms: z.ZodOptional<z.ZodNumber>;
+};
+declare const browserWaitForSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    condition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text_visible">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ref_exists">;
+        query: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url_matches">;
+        pattern: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"idle">;
+        ms: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const browserScreenshotShape: {
+    readonly session_id: z.ZodString;
+    readonly full_page: z.ZodOptional<z.ZodBoolean>;
+};
+declare const browserScreenshotSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    full_page: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const browserNavigateShape: {
+    readonly session_id: z.ZodString;
+    readonly url: z.ZodString;
+};
+declare const browserNavigateSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+declare const verifyUiFlowShape: {
+    readonly mode: z.ZodDefault<z.ZodEnum<{
+        assert: "assert";
+        reproduce: "reproduce";
+    }>>;
+    readonly open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly steps: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"click">;
+        query: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"type">;
+        query: z.ZodString;
+        text: z.ZodString;
+        clear_first: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"key">;
+        key: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"wait_for">;
+        condition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text_visible">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"ref_exists">;
+            query: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"url_matches">;
+            pattern: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"idle">;
+            ms: z.ZodNumber;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"navigate">;
+        url: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+    readonly expect: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text_visible">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"text_absent">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url_matches">;
+        pattern: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ref_in_state">;
+        query: z.ZodString;
+        state: z.ZodEnum<{
+            focused: "focused";
+            visible: "visible";
+            enabled: "enabled";
+        }>;
+    }, z.core.$strip>], "kind">>>;
+    readonly capture: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        screenshot: "screenshot";
+        har: "har";
+        console: "console";
+        a11y_tree: "a11y_tree";
+        video: "video";
+    }>>>;
+    readonly close_on_finish: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Only consulted when `mode='reproduce'`. When true (default) and the
+     * initial run reproduces the bug, the composite tries to remove each
+     * step in turn and re-runs to find a smaller reproducer.
+     */
+    readonly minimize: z.ZodDefault<z.ZodBoolean>;
+};
+declare const verifyUiFlowSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        assert: "assert";
+        reproduce: "reproduce";
+    }>>;
+    open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"click">;
+        query: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"type">;
+        query: z.ZodString;
+        text: z.ZodString;
+        clear_first: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"key">;
+        key: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"wait_for">;
+        condition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text_visible">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"ref_exists">;
+            query: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"url_matches">;
+            pattern: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"idle">;
+            ms: z.ZodNumber;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"navigate">;
+        url: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+    expect: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text_visible">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"text_absent">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url_matches">;
+        pattern: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ref_in_state">;
+        query: z.ZodString;
+        state: z.ZodEnum<{
+            focused: "focused";
+            visible: "visible";
+            enabled: "enabled";
+        }>;
+    }, z.core.$strip>], "kind">>>;
+    capture: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        screenshot: "screenshot";
+        har: "har";
+        console: "console";
+        a11y_tree: "a11y_tree";
+        video: "video";
+    }>>>;
+    close_on_finish: z.ZodDefault<z.ZodBoolean>;
+    minimize: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const auditA11yShape: {
+    readonly open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly level: z.ZodDefault<z.ZodEnum<{
+        "wcag-a": "wcag-a";
+        "wcag-aa": "wcag-aa";
+        "wcag-aaa": "wcag-aaa";
+    }>>;
+    readonly scope: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"page">, z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strip>]>>;
+    readonly report_format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        markdown: "markdown";
+    }>>;
+    readonly close_on_finish: z.ZodDefault<z.ZodBoolean>;
+};
+declare const auditA11ySchema: z.ZodObject<{
+    open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    level: z.ZodDefault<z.ZodEnum<{
+        "wcag-a": "wcag-a";
+        "wcag-aa": "wcag-aa";
+        "wcag-aaa": "wcag-aaa";
+    }>>;
+    scope: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"page">, z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strip>]>>;
+    report_format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        markdown: "markdown";
+    }>>;
+    close_on_finish: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const visualDiffShape: {
+    readonly open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly baseline_id: z.ZodString;
+    readonly viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    readonly threshold_pct: z.ZodDefault<z.ZodNumber>;
+    readonly close_on_finish: z.ZodDefault<z.ZodBoolean>;
+    /** Pixel sensitivity for pixelmatch (0 = strict, 1 = lax). Default 0.1. */
+    readonly pixel_threshold: z.ZodDefault<z.ZodNumber>;
+};
+declare const visualDiffSchema: z.ZodObject<{
+    open: z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    baseline_id: z.ZodString;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    threshold_pct: z.ZodDefault<z.ZodNumber>;
+    close_on_finish: z.ZodDefault<z.ZodBoolean>;
+    pixel_threshold: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const scaffoldE2eShape: {
+    readonly framework: z.ZodEnum<{
+        "playwright-test": "playwright-test";
+        "vitest+playwright": "vitest+playwright";
+        "pytest+selenium": "pytest+selenium";
+    }>;
+    readonly scenario_nl: z.ZodString;
+    readonly url: z.ZodString;
+    readonly recorded_bundle: z.ZodOptional<z.ZodString>;
+    /** Override the generated test file name. */
+    readonly filename: z.ZodOptional<z.ZodString>;
+};
+declare const scaffoldE2eSchema: z.ZodObject<{
+    framework: z.ZodEnum<{
+        "playwright-test": "playwright-test";
+        "vitest+playwright": "vitest+playwright";
+        "pytest+selenium": "pytest+selenium";
+    }>;
+    scenario_nl: z.ZodString;
+    url: z.ZodString;
+    recorded_bundle: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const extractUiStateShape: {
+    readonly session_id: z.ZodOptional<z.ZodString>;
+    readonly open: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    readonly question_nl: z.ZodString;
+    readonly close_on_finish: z.ZodDefault<z.ZodBoolean>;
+};
+declare const extractUiStateSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    open: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodDefault<z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        bundle_id: z.ZodOptional<z.ZodString>;
+        device: z.ZodOptional<z.ZodString>;
+        app_package: z.ZodOptional<z.ZodString>;
+        app_activity: z.ZodOptional<z.ZodString>;
+        emulator: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        user_agent: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    question_nl: z.ZodString;
+    close_on_finish: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const ToolNames: {
+    readonly browserOpen: "rolepod_browser_open";
+    readonly browserClose: "rolepod_browser_close";
+    readonly browserSnapshot: "rolepod_browser_snapshot";
+    readonly browserClick: "rolepod_browser_click";
+    readonly browserType: "rolepod_browser_type";
+    readonly browserKey: "rolepod_browser_key";
+    readonly browserScroll: "rolepod_browser_scroll";
+    readonly browserWaitFor: "rolepod_browser_wait_for";
+    readonly browserScreenshot: "rolepod_browser_screenshot";
+    readonly browserNavigate: "rolepod_browser_navigate";
+    readonly verifyUiFlow: "rolepod_verify_ui_flow";
+    readonly auditA11y: "rolepod_audit_a11y";
+    readonly visualDiff: "rolepod_visual_diff";
+    readonly scaffoldE2e: "rolepod_scaffold_e2e";
+    readonly extractUiState: "rolepod_extract_ui_state";
+};
+type ToolName = (typeof ToolNames)[keyof typeof ToolNames];
+
+/**
+ * The single seam between rolepod-uiproof's tool layer and any
+ * browser/mobile automation backend.
+ *
+ * Implementations: PlaywrightEngine (web), AppiumEngine (iOS + Android),
+ * optional SeleniumEngine (legacy grid, not yet implemented).
+ */
+type Platform = "web" | "ios" | "android";
+type Direction = "up" | "down" | "left" | "right";
+type WaitCondition = {
+    kind: "text_visible";
+    text: string;
+} | {
+    kind: "ref_exists";
+    query: string;
+} | {
+    kind: "url_matches";
+    pattern: string;
+} | {
+    kind: "idle";
+    ms: number;
+};
+type OpenOptions = {
+    platform: Platform;
+    url?: string;
+    browser?: "chromium" | "firefox" | "webkit";
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    headless?: boolean;
+    user_agent?: string;
+    locale?: string;
+    bundle_id?: string;
+    device?: string;
+    app_package?: string;
+    app_activity?: string;
+    emulator?: string;
+};
+/** Opaque session handle returned by `Engine.open`. */
+interface Session {
+    readonly id: string;
+    readonly platform: Platform;
+}
+type A11ySnapshot = {
+    session_id: string;
+    platform: Platform;
+    url_or_screen: string;
+    taken_at: string;
+    tree: A11yNode;
+    /** Screenshot buffer captured alongside the snapshot, if requested. */
+    screenshot?: Buffer;
+};
+interface Engine {
+    readonly id: "playwright" | "appium" | "selenium";
+    open(opts: OpenOptions): Promise<Session>;
+    close(session: Session): Promise<void>;
+    snapshot(session: Session, mode?: "visible" | "full"): Promise<A11ySnapshot>;
+    click(session: Session, ref: string, opts?: {
+        button?: "left" | "right" | "middle";
+    }): Promise<void>;
+    type(session: Session, ref: string, text: string, opts?: {
+        clearFirst?: boolean;
+    }): Promise<void>;
+    key(session: Session, key: string): Promise<void>;
+    scroll(session: Session, dir: Direction, amount?: number, ref?: string): Promise<void>;
+    waitFor(session: Session, cond: WaitCondition, timeoutMs?: number): Promise<void>;
+    screenshot(session: Session, fullPage?: boolean): Promise<Buffer>;
+    /** Web-only. Throws `unsupported_platform` on mobile sessions. */
+    navigate(session: Session, url: string): Promise<void>;
+}
+
+/**
+ * Routes sessions to the correct engine and enforces idle-timeout cleanup.
+ *
+ * v0.1: only PlaywrightEngine is wired up, so every `platform: 'web'`
+ * request goes there. AppiumEngine (v0.3) will register against the
+ * `ios`/`android` platform keys without touching tool code.
+ */
+declare class SessionRegistry {
+    private readonly enginesByPlatform;
+    private readonly engineBySession;
+    private readonly platformBySession;
+    private readonly lastActivity;
+    private readonly idleTimeoutMs;
+    private idleTimer;
+    constructor(opts?: {
+        idleTimeoutMs?: number;
+    });
+    /** Register an engine as the handler for a given platform. */
+    register(platform: Platform, engine: Engine): void;
+    open(opts: OpenOptions): Promise<Session>;
+    engineFor(sessionId: string): Engine;
+    close(session: Session): Promise<void>;
+    /** Look up the platform recorded for an open session. */
+    platformOf(sessionId: string): Platform;
+    shutdown(): Promise<void>;
+    private touch;
+    private platformFor;
+    private ensureIdleSweep;
+}
+
+declare const SERVER_NAME = "rolepod-uiproof";
+declare const SERVER_VERSION = "0.4.0";
+type ServerHandle = {
+    mcp: McpServer;
+    registry: SessionRegistry;
+    store: ArtifactStore;
+    shutdown(): Promise<void>;
+};
+/**
+ * Build the MCP server with every v0.1 tool registered. Caller is
+ * responsible for choosing a transport (stdio for production, in-memory
+ * for tests) and invoking `mcp.connect(transport)`.
+ */
+declare function buildServer(opts?: {
+    artifactRoot?: string;
+    idleTimeoutMs?: number;
+}): ServerHandle;
+
+/**
+ * PlaywrightEngine — v0.1 web-only implementation backed by Playwright's
+ * Chromium / Firefox / WebKit drivers and the built-in
+ * `page.accessibility.snapshot()` API.
+ *
+ * The interface contract (Engine.ts) is shared with AppiumEngine and the
+ * optional SeleniumEngine.
+ */
+declare class PlaywrightEngine implements Engine {
+    readonly id: "playwright";
+    private readonly sessions;
+    open(opts: OpenOptions): Promise<Session>;
+    close(session: Session): Promise<void>;
+    snapshot(session: Session, mode?: "visible" | "full"): Promise<A11ySnapshot>;
+    click(session: Session, ref: string, opts?: {
+        button?: "left" | "right" | "middle";
+    }): Promise<void>;
+    type(session: Session, ref: string, text: string, opts?: {
+        clearFirst?: boolean;
+    }): Promise<void>;
+    key(session: Session, key: string): Promise<void>;
+    scroll(session: Session, dir: Direction, amount?: number, ref?: string): Promise<void>;
+    waitFor(session: Session, cond: WaitCondition, timeoutMs?: number): Promise<void>;
+    screenshot(session: Session, fullPage?: boolean): Promise<Buffer>;
+    navigate(session: Session, url: string): Promise<void>;
+    /**
+     * Composite-only escape hatch — exposes the raw Playwright Page so a
+     * composite tool that genuinely needs page-level APIs (axe-core,
+     * `getByText`, etc.) can use them without bloating the Engine interface
+     * with web-specific verbs. Throws if the session is not web.
+     */
+    getPageForSession(sessionId: string): Page;
+    /** Increment generation; the next ref-using call will see them as stale. */
+    bumpGeneration(sessionId: string): void;
+    private requireSession;
+    private resolveLocator;
+    private invalidateRefs;
+    /**
+     * Test / shutdown helper. Closes every open session.
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * AppiumEngine — v0.3 mobile support via Appium 2.x + webdriverio.
+ *
+ * webdriverio is an `optionalDependency` (brief D-020). The engine
+ * lazy-imports it; if missing, every public method throws a structured
+ * `engine_error` with installation guidance.
+ *
+ * Smoke tests run against a real simulator only when one is reachable;
+ * unit tests for AT normalization use fixture XML strings (see
+ * `tests/unit/`).
+ */
+declare class AppiumEngine implements Engine {
+    readonly id: "appium";
+    private readonly sessions;
+    private wdioCache;
+    open(opts: OpenOptions): Promise<Session>;
+    close(session: Session): Promise<void>;
+    snapshot(session: Session, _mode?: "visible" | "full"): Promise<A11ySnapshot>;
+    click(session: Session, ref: string): Promise<void>;
+    type(session: Session, ref: string, text: string, opts?: {
+        clearFirst?: boolean;
+    }): Promise<void>;
+    key(session: Session, key: string): Promise<void>;
+    scroll(session: Session, dir: Direction, amount?: number, _ref?: string): Promise<void>;
+    waitFor(session: Session, cond: WaitCondition, timeoutMs?: number): Promise<void>;
+    screenshot(session: Session, _fullPage?: boolean): Promise<Buffer>;
+    navigate(_session: Session, _url: string): Promise<void>;
+    private loadWdio;
+    private buildCapabilities;
+    private screenIdentifier;
+    private requireSession;
+    private resolveElement;
+    private toSelector;
+    private invalidateRefs;
+}
+
+/**
+ * Engine selection happens once at server startup. v0.3 wires
+ * Playwright for `web` and Appium for `ios`/`android`. The
+ * `ROLEPOD_MCP_WEB_ENGINE` env var (D-012) only governs the *web*
+ * engine; mobile always routes to Appium.
+ */
+declare function createWebEngine(): Engine;
+declare function createMobileEngine(): Engine;
+/** Back-compat alias for v0.1 callers. */
+declare function createEngine(): Engine;
+
+/**
+ * Structured error types surfaced to MCP clients. Each carries enough
+ * context for the Lead agent to recover (typically: re-snapshot, then retry).
+ *
+ * Snapshot freshness rule: any state-changing call invalidates the current
+ * ref index; a stale ref returns `stale_ref` with the last valid snapshot
+ * timestamp so the Lead can re-snapshot and retry.
+ */
+type ErrorCode = "stale_ref" | "unknown_ref" | "unknown_session" | "unsupported_platform" | "unsupported_engine" | "not_implemented_in_v01" | "not_implemented_in_v02" | "invalid_input" | "engine_error";
+declare class RolepodMcpError extends Error {
+    readonly code: ErrorCode;
+    readonly detail?: Record<string, unknown> | undefined;
+    readonly name = "RolepodMcpError";
+    constructor(code: ErrorCode, message: string, detail?: Record<string, unknown> | undefined);
+    toJSON(): {
+        code: ErrorCode;
+        message: string;
+        detail?: Record<string, unknown>;
+    };
+}
+declare class StaleRefError extends RolepodMcpError {
+    constructor(sessionId: string, ref: string, lastValidSnapshotAt: string | null);
+}
+declare class UnknownRefError extends RolepodMcpError {
+    constructor(sessionId: string, ref: string);
+}
+declare class UnknownSessionError extends RolepodMcpError {
+    constructor(sessionId: string);
+}
+declare class UnsupportedPlatformError extends RolepodMcpError {
+    constructor(platform: string);
+}
+
+export { type A11yNode, type A11ySnapshot, AppiumEngine, ArtifactStore, type Engine, type OpenOptions, type Platform, PlaywrightEngine, RolepodMcpError, SERVER_NAME, SERVER_VERSION, type ServerHandle, type Session, SessionRegistry, StaleRefError, type ToolName, ToolNames, UnknownRefError, UnknownSessionError, UnsupportedPlatformError, type WaitCondition, auditA11ySchema, auditA11yShape, browserClickSchema, browserClickShape, browserCloseSchema, browserCloseShape, browserKeySchema, browserKeyShape, browserNavigateSchema, browserNavigateShape, browserOpenSchema, browserOpenShape, browserScreenshotSchema, browserScreenshotShape, browserScrollSchema, browserScrollShape, browserSnapshotSchema, browserSnapshotShape, browserTypeSchema, browserTypeShape, browserWaitForSchema, browserWaitForShape, buildServer, createEngine, createMobileEngine, createWebEngine, extractUiStateSchema, extractUiStateShape, scaffoldE2eSchema, scaffoldE2eShape, verifyUiFlowSchema, verifyUiFlowShape, visualDiffSchema, visualDiffShape };