@docsxai/engine 0.2.0

package/dist/doc-pack.d.ts

@@ -0,0 +1,1814 @@
+import { z } from "zod";
+export declare const ArrowStyle: z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>;
+export type ArrowStyle = z.infer<typeof ArrowStyle>;
+/** A locator reference (`$play_button`) resolved against a flow-file's `locators` map, or an inline selector. */
+export declare const LocatorRef: z.ZodString;
+export type LocatorRef = z.infer<typeof LocatorRef>;
+export declare const ActionType: z.ZodEnum<["navigate", "click", "fill", "upload", "press", "hover", "select", "check", "uncheck", "wait"]>;
+export type ActionType = z.infer<typeof ActionType>;
+/**
+ * What to wait for after a step's action settles. `network_idle` / `element_stable` / `load` are named
+ * primitives; `{ selector }` waits for an element to appear (Playwright's default timeout, ~30s) — give it
+ * `timeout_ms` to override that (e.g. waiting on a multi-minute backend op that mounts a "done" element);
+ * `{ timeout_ms }` alone is a blind sleep (last resort — for animations, not state).
+ */
+export declare const WaitSpec: z.ZodUnion<[z.ZodEnum<["network_idle", "element_stable", "load"]>, z.ZodObject<{
+    timeout_ms: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    timeout_ms: number;
+}, {
+    timeout_ms: number;
+}>, z.ZodObject<{
+    selector: z.ZodString;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    selector: string;
+    timeout_ms?: number | undefined;
+}, {
+    selector: string;
+    timeout_ms?: number | undefined;
+}>]>;
+export type WaitSpec = z.infer<typeof WaitSpec>;
+/** Post-step success criterion. Execution halts if it fails (no selector fallbacks — drift is a signal). */
+export declare const SuccessSpec: z.ZodUnion<[z.ZodObject<{
+    visible: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    visible: string;
+}, {
+    visible: string;
+}>, z.ZodObject<{
+    hidden: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    hidden: string;
+}, {
+    hidden: string;
+}>, z.ZodObject<{
+    url_matches: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    url_matches: string;
+}, {
+    url_matches: string;
+}>, z.ZodObject<{
+    text_contains: z.ZodObject<{
+        selector: z.ZodString;
+        text: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        text: string;
+    }, {
+        selector: string;
+        text: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    text_contains: {
+        selector: string;
+        text: string;
+    };
+}, {
+    text_contains: {
+        selector: string;
+        text: string;
+    };
+}>]>;
+export type SuccessSpec = z.infer<typeof SuccessSpec>;
+export declare const NudgeOffset: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    x: number;
+    y: number;
+}, {
+    x: number;
+    y: number;
+}>;
+export type NudgeOffset = z.infer<typeof NudgeOffset>;
+export declare const ViewportSize: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    width: number;
+    height: number;
+}, {
+    width: number;
+    height: number;
+}>;
+export type ViewportSize = z.infer<typeof ViewportSize>;
+export declare const ViewportPreset: z.ZodEnum<["desktop", "tablet", "mobile"]>;
+export type ViewportPreset = z.infer<typeof ViewportPreset>;
+/** Named viewport presets — `desktop` 1440×900, `tablet` 834×1112, `mobile` 390×844. */
+export declare const VIEWPORT_PRESETS: Record<ViewportPreset, ViewportSize>;
+/**
+ * Deterministic execution environment for a flow. All fields optional; applied at browser-context
+ * creation (so the whole flow runs under them). With `extends`, the child flow's `environment`
+ * wins per-key over the parent's (a child can pin just `viewport` and inherit the parent's clock).
+ */
+export declare const EnvironmentSpec: z.ZodObject<{
+    /** ISO-8601 instant the page clock is frozen at — `new Date()` etc. return this for the whole run. */
+    clock: z.ZodOptional<z.ZodString>;
+    /** BCP-47 language tag (e.g. `en-GB`). */
+    locale: z.ZodOptional<z.ZodString>;
+    /** IANA timezone (e.g. `Europe/Amsterdam`). */
+    timezone: z.ZodOptional<z.ZodString>;
+    /** `{ width, height }` in CSS pixels, or a named preset — see {@link VIEWPORT_PRESETS}. */
+    viewport: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["desktop", "tablet", "mobile"]>, z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>]>>;
+    color_scheme: z.ZodOptional<z.ZodEnum<["light", "dark"]>>;
+    reduced_motion: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    clock?: string | undefined;
+    locale?: string | undefined;
+    timezone?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | "desktop" | "tablet" | "mobile" | undefined;
+    color_scheme?: "light" | "dark" | undefined;
+    reduced_motion?: boolean | undefined;
+}, {
+    clock?: string | undefined;
+    locale?: string | undefined;
+    timezone?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | "desktop" | "tablet" | "mobile" | undefined;
+    color_scheme?: "light" | "dark" | undefined;
+    reduced_motion?: boolean | undefined;
+}>;
+export type EnvironmentSpec = z.infer<typeof EnvironmentSpec>;
+export declare const RedactionStyle: z.ZodEnum<["box", "pixelate"]>;
+export type RedactionStyle = z.infer<typeof RedactionStyle>;
+/** A fixed rectangle in CSS pixels (viewport coordinates), scaled to device pixels at capture time. */
+export declare const RedactionRegion: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+export type RedactionRegion = z.infer<typeof RedactionRegion>;
+/**
+ * One area to mask on every screenshot it applies to (step shots *and* halt shots): either an
+ * element (locator ref / inline selector, resolved to its bounding box at capture time) or a fixed
+ * `region`. Default `style` is `box` (solid #000 fill); `pixelate` is a 16-px mosaic. A selector
+ * that matches nothing at capture time is skipped with a stderr warning — redacting an absent
+ * element is vacuously satisfied, never a halt. Flow-level `redactions` apply to every step;
+ * per-step `redactions` are additive.
+ */
+export declare const RedactionSpec: z.ZodUnion<[z.ZodObject<{
+    selector: z.ZodString;
+    style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+}, "strict", z.ZodTypeAny, {
+    selector: string;
+    style?: "box" | "pixelate" | undefined;
+}, {
+    selector: string;
+    style?: "box" | "pixelate" | undefined;
+}>, z.ZodObject<{
+    region: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+}, "strict", z.ZodTypeAny, {
+    region: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    style?: "box" | "pixelate" | undefined;
+}, {
+    region: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    style?: "box" | "pixelate" | undefined;
+}>]>;
+export type RedactionSpec = z.infer<typeof RedactionSpec>;
+export declare const StepAnnotation: z.ZodObject<{
+    copy: z.ZodString;
+    arrow: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+    /**
+     * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+     * highlights the target element) stays on the target. Use this when two annotations on the same
+     * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+     * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+     */
+    nudge: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>>;
+    /**
+     * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+     * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+     * a *different* element is what you want to highlight in the resulting state. Point this at the
+     * surviving / appearing element.
+     */
+    target: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    copy: string;
+    arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+    nudge?: {
+        x: number;
+        y: number;
+    } | undefined;
+    target?: string | undefined;
+}, {
+    copy: string;
+    arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+    nudge?: {
+        x: number;
+        y: number;
+    } | undefined;
+    target?: string | undefined;
+}>;
+export type StepAnnotation = z.infer<typeof StepAnnotation>;
+export declare const Step: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    action: z.ZodEnum<["navigate", "click", "fill", "upload", "press", "hover", "select", "check", "uncheck", "wait"]>;
+    /**
+     * Best-effort step: if the action / `wait_for` / `success` check throws (target absent, wait timed
+     * out, etc.), **skip this step and continue** instead of halting the flow. For conditionally-present
+     * UI — a confirmation modal that sometimes appears, a first-run tooltip, a cookie banner. A skipped
+     * optional step emits no screenshot / annotation (same as a step skipped by `--start-from`). Prefer
+     * this over a permissive comma-selector that no-ops on one branch.
+     */
+    optional: z.ZodOptional<z.ZodBoolean>;
+    /** Locator ref (`$name`) or inline selector. Optional for actions like `navigate` (uses `value`) or `wait`. */
+    target: z.ZodOptional<z.ZodString>;
+    /** Action payload: text for `fill`, file path for `upload`, key for `press`, path/URL for `navigate`, option for `select`. */
+    value: z.ZodOptional<z.ZodString>;
+    wait_for: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["network_idle", "element_stable", "load"]>, z.ZodObject<{
+        timeout_ms: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        timeout_ms: number;
+    }, {
+        timeout_ms: number;
+    }>, z.ZodObject<{
+        selector: z.ZodString;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        timeout_ms?: number | undefined;
+    }, {
+        selector: string;
+        timeout_ms?: number | undefined;
+    }>]>>;
+    success: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        visible: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        visible: string;
+    }, {
+        visible: string;
+    }>, z.ZodObject<{
+        hidden: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        hidden: string;
+    }, {
+        hidden: string;
+    }>, z.ZodObject<{
+        url_matches: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        url_matches: string;
+    }, {
+        url_matches: string;
+    }>, z.ZodObject<{
+        text_contains: z.ZodObject<{
+            selector: z.ZodString;
+            text: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            selector: string;
+            text: string;
+        }, {
+            selector: string;
+            text: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    }, {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    }>]>>;
+    /** Single call-out on this step's screenshot. Shorthand for a one-element `annotations` array. */
+    annotation: z.ZodOptional<z.ZodObject<{
+        copy: z.ZodString;
+        arrow: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+        /**
+         * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+         * highlights the target element) stays on the target. Use this when two annotations on the same
+         * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+         * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+         */
+        nudge: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>>;
+        /**
+         * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+         * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+         * a *different* element is what you want to highlight in the resulting state. Point this at the
+         * surviving / appearing element.
+         */
+        target: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }, {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }>>;
+    /**
+     * Multiple call-outs on the same screenshot — rendered as numbered badges (1, 2, …) so the reader sees
+     * up front that there's more than one thing to look at without having to hover everything. Each entry
+     * has its own `target` (defaults to the step's `target`) and `copy` / `arrow` — see {@link StepAnnotation}.
+     * Mutually exclusive with `annotation`.
+     */
+    annotations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        copy: z.ZodString;
+        arrow: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+        /**
+         * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+         * highlights the target element) stays on the target. Use this when two annotations on the same
+         * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+         * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+         */
+        nudge: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>>;
+        /**
+         * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+         * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+         * a *different* element is what you want to highlight in the resulting state. Point this at the
+         * surviving / appearing element.
+         */
+        target: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }, {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }>, "many">>;
+    /** Extra redactions for this step's screenshots, additive on top of the flow-level list. */
+    redactions: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        selector: z.ZodString;
+        style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    }, {
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    }>, z.ZodObject<{
+        region: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>;
+        style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+    }, "strict", z.ZodTypeAny, {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    }, {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    }>]>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+    value?: string | undefined;
+    target?: string | undefined;
+    optional?: boolean | undefined;
+    wait_for?: "network_idle" | "element_stable" | "load" | {
+        timeout_ms: number;
+    } | {
+        selector: string;
+        timeout_ms?: number | undefined;
+    } | undefined;
+    success?: {
+        visible: string;
+    } | {
+        hidden: string;
+    } | {
+        url_matches: string;
+    } | {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    } | undefined;
+    annotation?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    } | undefined;
+    annotations?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }[] | undefined;
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+}, {
+    id: string;
+    action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+    value?: string | undefined;
+    target?: string | undefined;
+    optional?: boolean | undefined;
+    wait_for?: "network_idle" | "element_stable" | "load" | {
+        timeout_ms: number;
+    } | {
+        selector: string;
+        timeout_ms?: number | undefined;
+    } | undefined;
+    success?: {
+        visible: string;
+    } | {
+        hidden: string;
+    } | {
+        url_matches: string;
+    } | {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    } | undefined;
+    annotation?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    } | undefined;
+    annotations?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }[] | undefined;
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+}>, {
+    id: string;
+    action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+    value?: string | undefined;
+    target?: string | undefined;
+    optional?: boolean | undefined;
+    wait_for?: "network_idle" | "element_stable" | "load" | {
+        timeout_ms: number;
+    } | {
+        selector: string;
+        timeout_ms?: number | undefined;
+    } | undefined;
+    success?: {
+        visible: string;
+    } | {
+        hidden: string;
+    } | {
+        url_matches: string;
+    } | {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    } | undefined;
+    annotation?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    } | undefined;
+    annotations?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }[] | undefined;
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+}, {
+    id: string;
+    action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+    value?: string | undefined;
+    target?: string | undefined;
+    optional?: boolean | undefined;
+    wait_for?: "network_idle" | "element_stable" | "load" | {
+        timeout_ms: number;
+    } | {
+        selector: string;
+        timeout_ms?: number | undefined;
+    } | undefined;
+    success?: {
+        visible: string;
+    } | {
+        hidden: string;
+    } | {
+        url_matches: string;
+    } | {
+        text_contains: {
+            selector: string;
+            text: string;
+        };
+    } | undefined;
+    annotation?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    } | undefined;
+    annotations?: {
+        copy: string;
+        arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        target?: string | undefined;
+    }[] | undefined;
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+}>;
+export type Step = z.infer<typeof Step>;
+/** A precondition the flow assumes (e.g. `{ logged_in_as: "editor" }`, `{ feature_flag: "recap.enabled" }`). */
+export declare const Prerequisite: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
+export type Prerequisite = z.infer<typeof Prerequisite>;
+export declare const FlowFile: z.ZodObject<{
+    name: z.ZodString;
+    /**
+     * Name of another flow whose steps run *first* (composition). The parent's `locators` + `prerequisites`
+     * are merged in (this flow wins on collisions); step ids must be unique across the merge. Chains allowed
+     * (A extends B extends C); cycles are rejected. Resolved at run time against `flows/<name>.flow.yaml`.
+     * Typical use: factor out a shared preamble (Library → open a video → editor) so dependent flows don't
+     * re-walk it every run. (`run --stop-after` operates on the merged step list.)
+     */
+    extends: z.ZodOptional<z.ZodString>;
+    /**
+     * Deterministic execution environment (frozen clock, locale, timezone, viewport, color scheme,
+     * reduced motion). With `extends`, merged per-key — this flow's keys win over the parent's.
+     */
+    environment: z.ZodOptional<z.ZodObject<{
+        /** ISO-8601 instant the page clock is frozen at — `new Date()` etc. return this for the whole run. */
+        clock: z.ZodOptional<z.ZodString>;
+        /** BCP-47 language tag (e.g. `en-GB`). */
+        locale: z.ZodOptional<z.ZodString>;
+        /** IANA timezone (e.g. `Europe/Amsterdam`). */
+        timezone: z.ZodOptional<z.ZodString>;
+        /** `{ width, height }` in CSS pixels, or a named preset — see {@link VIEWPORT_PRESETS}. */
+        viewport: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["desktop", "tablet", "mobile"]>, z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width: number;
+            height: number;
+        }>]>>;
+        color_scheme: z.ZodOptional<z.ZodEnum<["light", "dark"]>>;
+        reduced_motion: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        clock?: string | undefined;
+        locale?: string | undefined;
+        timezone?: string | undefined;
+        viewport?: {
+            width: number;
+            height: number;
+        } | "desktop" | "tablet" | "mobile" | undefined;
+        color_scheme?: "light" | "dark" | undefined;
+        reduced_motion?: boolean | undefined;
+    }, {
+        clock?: string | undefined;
+        locale?: string | undefined;
+        timezone?: string | undefined;
+        viewport?: {
+            width: number;
+            height: number;
+        } | "desktop" | "tablet" | "mobile" | undefined;
+        color_scheme?: "light" | "dark" | undefined;
+        reduced_motion?: boolean | undefined;
+    }>>;
+    /** Areas masked on every screenshot this flow produces (incl. halt shots). See {@link RedactionSpec}. */
+    redactions: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        selector: z.ZodString;
+        style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    }, {
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    }>, z.ZodObject<{
+        region: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>;
+        style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+    }, "strict", z.ZodTypeAny, {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    }, {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    }>]>, "many">>;
+    prerequisites: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean]>>, "many">>;
+    /** Named canonical locators referenced from steps as `$name`. One per name; no fallback lists. */
+    locators: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    steps: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        action: z.ZodEnum<["navigate", "click", "fill", "upload", "press", "hover", "select", "check", "uncheck", "wait"]>;
+        /**
+         * Best-effort step: if the action / `wait_for` / `success` check throws (target absent, wait timed
+         * out, etc.), **skip this step and continue** instead of halting the flow. For conditionally-present
+         * UI — a confirmation modal that sometimes appears, a first-run tooltip, a cookie banner. A skipped
+         * optional step emits no screenshot / annotation (same as a step skipped by `--start-from`). Prefer
+         * this over a permissive comma-selector that no-ops on one branch.
+         */
+        optional: z.ZodOptional<z.ZodBoolean>;
+        /** Locator ref (`$name`) or inline selector. Optional for actions like `navigate` (uses `value`) or `wait`. */
+        target: z.ZodOptional<z.ZodString>;
+        /** Action payload: text for `fill`, file path for `upload`, key for `press`, path/URL for `navigate`, option for `select`. */
+        value: z.ZodOptional<z.ZodString>;
+        wait_for: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["network_idle", "element_stable", "load"]>, z.ZodObject<{
+            timeout_ms: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            timeout_ms: number;
+        }, {
+            timeout_ms: number;
+        }>, z.ZodObject<{
+            selector: z.ZodString;
+            timeout_ms: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            selector: string;
+            timeout_ms?: number | undefined;
+        }, {
+            selector: string;
+            timeout_ms?: number | undefined;
+        }>]>>;
+        success: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            visible: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            visible: string;
+        }, {
+            visible: string;
+        }>, z.ZodObject<{
+            hidden: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            hidden: string;
+        }, {
+            hidden: string;
+        }>, z.ZodObject<{
+            url_matches: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            url_matches: string;
+        }, {
+            url_matches: string;
+        }>, z.ZodObject<{
+            text_contains: z.ZodObject<{
+                selector: z.ZodString;
+                text: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                selector: string;
+                text: string;
+            }, {
+                selector: string;
+                text: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        }, {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        }>]>>;
+        /** Single call-out on this step's screenshot. Shorthand for a one-element `annotations` array. */
+        annotation: z.ZodOptional<z.ZodObject<{
+            copy: z.ZodString;
+            arrow: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+            /**
+             * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+             * highlights the target element) stays on the target. Use this when two annotations on the same
+             * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+             * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+             */
+            nudge: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>>;
+            /**
+             * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+             * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+             * a *different* element is what you want to highlight in the resulting state. Point this at the
+             * surviving / appearing element.
+             */
+            target: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }, {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }>>;
+        /**
+         * Multiple call-outs on the same screenshot — rendered as numbered badges (1, 2, …) so the reader sees
+         * up front that there's more than one thing to look at without having to hover everything. Each entry
+         * has its own `target` (defaults to the step's `target`) and `copy` / `arrow` — see {@link StepAnnotation}.
+         * Mutually exclusive with `annotation`.
+         */
+        annotations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            copy: z.ZodString;
+            arrow: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+            /**
+             * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+             * highlights the target element) stays on the target. Use this when two annotations on the same
+             * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+             * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+             */
+            nudge: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>>;
+            /**
+             * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+             * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+             * a *different* element is what you want to highlight in the resulting state. Point this at the
+             * surviving / appearing element.
+             */
+            target: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }, {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }>, "many">>;
+        /** Extra redactions for this step's screenshots, additive on top of the flow-level list. */
+        redactions: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            selector: z.ZodString;
+            style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+        }, "strict", z.ZodTypeAny, {
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        }, {
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        }>, z.ZodObject<{
+            region: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            }, {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            }>;
+            style: z.ZodOptional<z.ZodEnum<["box", "pixelate"]>>;
+        }, "strict", z.ZodTypeAny, {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        }, {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        }>]>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }, {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }>, {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }, {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    prerequisites: Record<string, string | boolean>[];
+    locators: Record<string, string>;
+    steps: {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }[];
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+    extends?: string | undefined;
+    environment?: {
+        clock?: string | undefined;
+        locale?: string | undefined;
+        timezone?: string | undefined;
+        viewport?: {
+            width: number;
+            height: number;
+        } | "desktop" | "tablet" | "mobile" | undefined;
+        color_scheme?: "light" | "dark" | undefined;
+        reduced_motion?: boolean | undefined;
+    } | undefined;
+}, {
+    name: string;
+    steps: {
+        id: string;
+        action: "fill" | "navigate" | "click" | "upload" | "press" | "hover" | "select" | "check" | "uncheck" | "wait";
+        value?: string | undefined;
+        target?: string | undefined;
+        optional?: boolean | undefined;
+        wait_for?: "network_idle" | "element_stable" | "load" | {
+            timeout_ms: number;
+        } | {
+            selector: string;
+            timeout_ms?: number | undefined;
+        } | undefined;
+        success?: {
+            visible: string;
+        } | {
+            hidden: string;
+        } | {
+            url_matches: string;
+        } | {
+            text_contains: {
+                selector: string;
+                text: string;
+            };
+        } | undefined;
+        annotation?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        } | undefined;
+        annotations?: {
+            copy: string;
+            arrow?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+            nudge?: {
+                x: number;
+                y: number;
+            } | undefined;
+            target?: string | undefined;
+        }[] | undefined;
+        redactions?: ({
+            selector: string;
+            style?: "box" | "pixelate" | undefined;
+        } | {
+            region: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            style?: "box" | "pixelate" | undefined;
+        })[] | undefined;
+    }[];
+    redactions?: ({
+        selector: string;
+        style?: "box" | "pixelate" | undefined;
+    } | {
+        region: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        style?: "box" | "pixelate" | undefined;
+    })[] | undefined;
+    extends?: string | undefined;
+    environment?: {
+        clock?: string | undefined;
+        locale?: string | undefined;
+        timezone?: string | undefined;
+        viewport?: {
+            width: number;
+            height: number;
+        } | "desktop" | "tablet" | "mobile" | undefined;
+        color_scheme?: "light" | "dark" | undefined;
+        reduced_motion?: boolean | undefined;
+    } | undefined;
+    prerequisites?: Record<string, string | boolean>[] | undefined;
+    locators?: Record<string, string> | undefined;
+}>;
+export type FlowFile = z.infer<typeof FlowFile>;
+export declare const BoundingBox: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+export type BoundingBox = z.infer<typeof BoundingBox>;
+export declare const AnnotationRecord: z.ZodObject<{
+    step: z.ZodString;
+    selector: z.ZodString;
+    bounding_box: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>>;
+    copy: z.ZodString;
+    arrow_style: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+    /** Optional pixel offset applied to the callout + arrow at render time — see {@link NudgeOffset}. */
+    nudge: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>>;
+    /** 1-based index of this annotation *within its step's screenshot* — set only when the step has > 1 annotation, so the viewer can render a numbered badge. Absent → render as a plain (un-numbered) halo. */
+    index: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    selector: string;
+    copy: string;
+    step: string;
+    nudge?: {
+        x: number;
+        y: number;
+    } | undefined;
+    bounding_box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+    index?: number | undefined;
+}, {
+    selector: string;
+    copy: string;
+    step: string;
+    nudge?: {
+        x: number;
+        y: number;
+    } | undefined;
+    bounding_box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+    index?: number | undefined;
+}>;
+export type AnnotationRecord = z.infer<typeof AnnotationRecord>;
+export declare const AnnotationsFile: z.ZodObject<{
+    schema: z.ZodLiteral<"docsxai/annotations@1">;
+    flow: z.ZodString;
+    annotations: z.ZodArray<z.ZodObject<{
+        step: z.ZodString;
+        selector: z.ZodString;
+        bounding_box: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }, {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>>;
+        copy: z.ZodString;
+        arrow_style: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"]>>;
+        /** Optional pixel offset applied to the callout + arrow at render time — see {@link NudgeOffset}. */
+        nudge: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>>;
+        /** 1-based index of this annotation *within its step's screenshot* — set only when the step has > 1 annotation, so the viewer can render a numbered badge. Absent → render as a plain (un-numbered) halo. */
+        index: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        copy: string;
+        step: string;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        bounding_box?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | undefined;
+        arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        index?: number | undefined;
+    }, {
+        selector: string;
+        copy: string;
+        step: string;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        bounding_box?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | undefined;
+        arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        index?: number | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    annotations: {
+        selector: string;
+        copy: string;
+        step: string;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        bounding_box?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | undefined;
+        arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        index?: number | undefined;
+    }[];
+    schema: "docsxai/annotations@1";
+    flow: string;
+}, {
+    annotations: {
+        selector: string;
+        copy: string;
+        step: string;
+        nudge?: {
+            x: number;
+            y: number;
+        } | undefined;
+        bounding_box?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | undefined;
+        arrow_style?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "left" | "right" | undefined;
+        index?: number | undefined;
+    }[];
+    schema: "docsxai/annotations@1";
+    flow: string;
+}>;
+export type AnnotationsFile = z.infer<typeof AnnotationsFile>;
+export declare const StyleArtifact: z.ZodObject<{
+    schema: z.ZodLiteral<"docsxai/style@1">;
+    voice: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    structure: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    terminology: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    visual: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    localisation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Categories of testing-jargon the commit stage must strip from user-facing prose. */
+    pruning_rules: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    schema: "docsxai/style@1";
+    voice?: Record<string, unknown> | undefined;
+    structure?: Record<string, unknown> | undefined;
+    terminology?: Record<string, string> | undefined;
+    visual?: Record<string, unknown> | undefined;
+    localisation?: Record<string, unknown> | undefined;
+    pruning_rules?: string[] | undefined;
+}, {
+    schema: "docsxai/style@1";
+    voice?: Record<string, unknown> | undefined;
+    structure?: Record<string, unknown> | undefined;
+    terminology?: Record<string, string> | undefined;
+    visual?: Record<string, unknown> | undefined;
+    localisation?: Record<string, unknown> | undefined;
+    pruning_rules?: string[] | undefined;
+}>;
+export type StyleArtifact = z.infer<typeof StyleArtifact>;
+export declare const LocatorManifest: z.ZodObject<{
+    schema: z.ZodLiteral<"docsxai/locators@1">;
+    /** flow name → locator name → canonical selector. One per name; no fallbacks. */
+    flows: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    schema: "docsxai/locators@1";
+    flows: Record<string, Record<string, string>>;
+}, {
+    schema: "docsxai/locators@1";
+    flows: Record<string, Record<string, string>>;
+}>;
+export type LocatorManifest = z.infer<typeof LocatorManifest>;
+export declare const StrategyName: z.ZodEnum<["api-login", "jwt-injection", "ui-form", "http-basic", "mtls", "pat-header", "email-otp", "totp", "webauthn", "manual-capture", "test-backdoor"]>;
+export type StrategyName = z.infer<typeof StrategyName>;
+/** `session` = use the captured session's own lifetime; otherwise a duration string (`30m`, `1h`) or ms number. */
+export declare const CacheTtl: z.ZodUnion<[z.ZodLiteral<"session">, z.ZodString, z.ZodNumber]>;
+export type CacheTtl = z.infer<typeof CacheTtl>;
+export declare const RoleAuth: z.ZodObject<{
+    strategy: z.ZodEnum<["api-login", "jwt-injection", "ui-form", "http-basic", "mtls", "pat-header", "email-otp", "totp", "webauthn", "manual-capture", "test-backdoor"]>;
+    /** Env-var *names* holding credentials — never the values. May be `{}` (e.g. `manual-capture` needs none). */
+    creds_env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        store: z.ZodDefault<z.ZodEnum<["local", "backend"]>>;
+        /** Fallback expiry when no `auth_cookie` is set/found: a duration, or `session` (→ a 1h default). */
+        ttl: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"session">, z.ZodString, z.ZodNumber]>>;
+        /**
+         * Name of the app's actual auth/session cookie. When set, the cached session's `expiresAt` is *that*
+         * cookie's expiry — the real bound — rather than the `ttl` guess. Identify it from the captured jar
+         * (`capture-auth` prints it): it's on the app's domain, long-lived (not an ephemeral IdP scratch
+         * cookie), e.g. `AppSession.Production` / `.AspNetCore.Cookies` / `session`. Optional.
+         */
+        auth_cookie: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        store: "local" | "backend";
+        ttl: string | number;
+        auth_cookie?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        store?: "local" | "backend" | undefined;
+        ttl?: string | number | undefined;
+        auth_cookie?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    options: Record<string, unknown>;
+    strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+    creds_env: Record<string, string>;
+    cache: {
+        enabled: boolean;
+        store: "local" | "backend";
+        ttl: string | number;
+        auth_cookie?: string | undefined;
+    };
+}, {
+    strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+    options?: Record<string, unknown> | undefined;
+    creds_env?: Record<string, string> | undefined;
+    cache?: {
+        enabled?: boolean | undefined;
+        store?: "local" | "backend" | undefined;
+        ttl?: string | number | undefined;
+        auth_cookie?: string | undefined;
+    } | undefined;
+}>;
+export type RoleAuth = z.infer<typeof RoleAuth>;
+export declare const AuthStrategyDescriptor: z.ZodEffects<z.ZodObject<{
+    schema: z.ZodLiteral<"docsxai/auth-strategy@1">;
+    default_role: z.ZodString;
+    roles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        strategy: z.ZodEnum<["api-login", "jwt-injection", "ui-form", "http-basic", "mtls", "pat-header", "email-otp", "totp", "webauthn", "manual-capture", "test-backdoor"]>;
+        /** Env-var *names* holding credentials — never the values. May be `{}` (e.g. `manual-capture` needs none). */
+        creds_env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        cache: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            store: z.ZodDefault<z.ZodEnum<["local", "backend"]>>;
+            /** Fallback expiry when no `auth_cookie` is set/found: a duration, or `session` (→ a 1h default). */
+            ttl: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"session">, z.ZodString, z.ZodNumber]>>;
+            /**
+             * Name of the app's actual auth/session cookie. When set, the cached session's `expiresAt` is *that*
+             * cookie's expiry — the real bound — rather than the `ttl` guess. Identify it from the captured jar
+             * (`capture-auth` prints it): it's on the app's domain, long-lived (not an ephemeral IdP scratch
+             * cookie), e.g. `AppSession.Production` / `.AspNetCore.Cookies` / `session`. Optional.
+             */
+            auth_cookie: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            enabled: boolean;
+            store: "local" | "backend";
+            ttl: string | number;
+            auth_cookie?: string | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            store?: "local" | "backend" | undefined;
+            ttl?: string | number | undefined;
+            auth_cookie?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        creds_env: Record<string, string>;
+        cache: {
+            enabled: boolean;
+            store: "local" | "backend";
+            ttl: string | number;
+            auth_cookie?: string | undefined;
+        };
+    }, {
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        options?: Record<string, unknown> | undefined;
+        creds_env?: Record<string, string> | undefined;
+        cache?: {
+            enabled?: boolean | undefined;
+            store?: "local" | "backend" | undefined;
+            ttl?: string | number | undefined;
+            auth_cookie?: string | undefined;
+        } | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    schema: "docsxai/auth-strategy@1";
+    default_role: string;
+    roles: Record<string, {
+        options: Record<string, unknown>;
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        creds_env: Record<string, string>;
+        cache: {
+            enabled: boolean;
+            store: "local" | "backend";
+            ttl: string | number;
+            auth_cookie?: string | undefined;
+        };
+    }>;
+}, {
+    schema: "docsxai/auth-strategy@1";
+    default_role: string;
+    roles: Record<string, {
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        options?: Record<string, unknown> | undefined;
+        creds_env?: Record<string, string> | undefined;
+        cache?: {
+            enabled?: boolean | undefined;
+            store?: "local" | "backend" | undefined;
+            ttl?: string | number | undefined;
+            auth_cookie?: string | undefined;
+        } | undefined;
+    }>;
+}>, {
+    schema: "docsxai/auth-strategy@1";
+    default_role: string;
+    roles: Record<string, {
+        options: Record<string, unknown>;
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        creds_env: Record<string, string>;
+        cache: {
+            enabled: boolean;
+            store: "local" | "backend";
+            ttl: string | number;
+            auth_cookie?: string | undefined;
+        };
+    }>;
+}, {
+    schema: "docsxai/auth-strategy@1";
+    default_role: string;
+    roles: Record<string, {
+        strategy: "api-login" | "jwt-injection" | "ui-form" | "http-basic" | "mtls" | "pat-header" | "email-otp" | "totp" | "webauthn" | "manual-capture" | "test-backdoor";
+        options?: Record<string, unknown> | undefined;
+        creds_env?: Record<string, string> | undefined;
+        cache?: {
+            enabled?: boolean | undefined;
+            store?: "local" | "backend" | undefined;
+            ttl?: string | number | undefined;
+            auth_cookie?: string | undefined;
+        } | undefined;
+    }>;
+}>;
+export type AuthStrategyDescriptor = z.infer<typeof AuthStrategyDescriptor>;
+export declare const RevisionKind: z.ZodEnum<["calibrate", "run", "edit"]>;
+export type RevisionKind = z.infer<typeof RevisionKind>;
+export declare const RevisionMeta: z.ZodObject<{
+    rev_id: z.ZodString;
+    parent_rev_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<["calibrate", "run", "edit"]>;
+    author: z.ZodString;
+    /** ISO-8601 timestamp. */
+    timestamp: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    rev_id: string;
+    parent_rev_id: string | null;
+    kind: "calibrate" | "run" | "edit";
+    author: string;
+    timestamp: string;
+}, {
+    rev_id: string;
+    parent_rev_id: string | null;
+    kind: "calibrate" | "run" | "edit";
+    author: string;
+    timestamp: string;
+}>;
+export type RevisionMeta = z.infer<typeof RevisionMeta>;