import type { Page } from '@playwright/test';
import { type NavigableItem } from './inventory.js';
import { type DataResidueEntry } from './data-residue.js';
/**
 * Computed-style capture: the browser's final resolved value for every CSS
 * longhand on every element, keyed by DOM structure (never by class name, so
 * a CSS-to-Tailwind migration can rewrite classes freely while the map stays
 * comparable). Three layers per capture:
 *
 *   elements — every element's computed style, pruned against per-tag UA
 *              defaults (measured in a clean iframe) to keep files small,
 *              plus ::before / ::after / ::marker / ::placeholder.
 *   states   — for interactive elements, what :hover, :focus(-visible) and
 *              :active change (forced via CDP, no mouse involved), captured
 *              as a delta over the element's subtree. Rest screenshots cannot
 *              see these; the `*.hover.png` / `*.focus.png` / `*.active.png`
 *              layers can. This is where dropped `hover:` variants get caught.
 *   motion   — transition/animation longhands are captured before the
 *              freeze-CSS below nulls them, so declared motion is verified
 *              too, while every other captured value is a settled end state.
 *
 * LIMITATIONS (documented, and warned at capture time):
 *   - Shadow DOM (open or closed) is NOT traversed: styles inside a web
 *     component's shadow root are invisible to the diff. A refactor inside a
 *     shadow tree would be falsely certified identical, so capture emits a
 *     one-time warning naming the shadow hosts it skipped.
 *   - Iframe content (same- or cross-origin) is NOT traversed for the same
 *     reason; same-origin frames are listed in the same warning.
 */
type Props = Record<string, string>;
/** Document-space bounding box: [x, y, width, height], rounded. */
export type Rect = [number, number, number, number];
export type ElementEntry = {
    tag: string;
    cls: string;
    rect?: Rect;
    style: Props;
    /**
     * CSS Typed OM computed values only where they differ from the legacy CSSOM
     * used value in `style` (for example `auto` versus a layout-resolved pixel
     * margin, `20%` versus a used pixel width, or `1fr` versus grid track pixels).
     * This compact signal lets the differ discard layout reflow while preserving
     * a real declaration/computed-value change. Absent on legacy captures, which
     * deliberately remain fail-closed.
     */
    computedValueStyle?: Props;
    pseudo?: Record<string, Props>;
    /**
     * Length of the element's own rendered text after whitespace normalization.
     * Always captured, but never the text itself: this privacy-safe signal lets
     * the differ distinguish content-length reflow from a genuine sizing-rule
     * change without enabling the opt-in content layer.
     */
    ownTextLength?: number;
    /**
     * The element's OWN rendered text (direct text-node children only, whitespace
     * collapsed) — present only when capture ran with `captureText: true` (the
     * opt-in content layer, off by default). Own-text, not subtree text, so each
     * change is attributed to the single element that owns it. Diffed by
     * {@link diffContentMaps}, never by the certification diff — content is
     * advisory, not a computed-style outcome. See README "Optional: content layer".
     */
    text?: string;
    /**
     * The React component that rendered this element, and a sanitized subset of its
     * props — present only when capture ran with `captureComponent: true` (opt-in,
     * off by default). Extracted in-page from the React fiber. ADVISORY: never fed
     * to the certification diff or its counts (like {@link ElementEntry.text}); it
     * only enriches the report so a reviewer sees `Button (variant=primary)` rather
     * than a bare `<button>`. Best in dev/non-minified builds (prod mangles names).
     */
    component?: {
        name: string;
        props?: Record<string, string>;
    };
};
/** Report-only provenance for a surface expanded from {@link import('./state-recipes.js').StateRecipe}. Ignored by the certification diff. */
export type StateRecipeCaptureProvenance = {
    /** Stable recipe key (`hover-plan-card`, …) — same fragment joined into the capture key. */
    stateKey: string;
    action: 'hover' | 'focus' | 'press' | 'click';
    /** Validated value-free CSS selector (never attribute-equality / secret-bearing). */
    selector: string;
    /** Press key when action is `press`. */
    key?: string;
    /** Declared label when provided (not a live DOM label rewrite). */
    label?: string;
};
export type CaptureMetadata = {
    surfaceKey?: string;
    variantKey?: string;
    variantKind?: 'variant' | 'live-state' | 'popup' | 'state-recipe';
    /**
     * Provenance for `variantKind: 'state-recipe'` expansions. Report-only —
     * ignored by the certification diff (same as other metadata fields).
     */
    stateRecipe?: StateRecipeCaptureProvenance;
};
export type LiveRegionCandidate = {
    path: string;
    tag: string;
    cls: string;
    reason: string;
    role?: string;
    ariaLive?: string;
    ariaBusy?: string;
};
export type CapturedOverlay = {
    path: string;
    tag: string;
    cls: string;
    reason: string;
    role?: string;
    ariaModal?: string;
    ariaLive?: string;
    text?: string;
};
export type StyleMap = {
    /** Optional runner-supplied context; ignored by the certification diff. */
    metadata?: CaptureMetadata;
    /** Browser viewport used for this capture. Report-only; ignored by the certification diff. */
    viewport?: {
        width: number;
        height: number;
    };
    defaults: Record<string, Props>;
    elements: Record<string, ElementEntry>;
    states: Record<string, Record<string, Record<string, Props>>>;
    /**
     * True when the forced :hover/:focus/:active layer was not fully captured for
     * this capture — either CDP/page interactive-element count skew, or because the
     * interactive-element count exceeded `maxInteractive` and capture was truncated.
     * Persisted so a diff against a fully-captured side flags that the state layer
     * wasn't certified, instead of silently reading as "identical".
     */
    statesSkipped?: boolean;
    /**
     * Element paths detected as LIVE at capture time — they kept changing on
     * their own (after motion was frozen) until the settle budget ran out, so
     * they're nondeterministic. Excluded from `elements`/`states`/`defaults`
     * here, and skipped by the diff (which unions both sides' volatile sets) so a
     * stream/ticker never reads as a change. Empty/absent on a fully-settled page.
     */
    volatile?: string[];
    /**
     * Semantic live-state candidates detected automatically from the DOM, such as
     * `[aria-live]`, `role=status`, `role=alert`, or `aria-busy=true`. These are
     * diagnostics only: stable candidates are still captured and compared; only
     * regions that actually keep changing are auto-excluded via `volatile`.
     */
    liveCandidates?: LiveRegionCandidate[];
    /**
     * Visible semantic overlay roots that were present in the captured DOM and
     * whose paths are present in `elements`. This is diagnostic/proof metadata:
     * dialogs, menus, listboxes, modal roots and toast roots are still certified by
     * the normal computed-style map, while this list lets tests prove those states
     * were actually reached and captured.
     */
    overlays?: CapturedOverlay[];
    /**
     * Colour-valued `:root` custom properties (design/theme tokens), normalised to
     * the same `rgb(...)` form the longhands resolve to — `{ "--red-200": "rgb(254,
     * 202, 202)" }`. Lets the report name the token behind a colour change
     * (`red-100 → red-200`) instead of only the raw value. Captured once per
     * surface from the document root; per-subtree overrides aren't tracked.
     */
    tokens?: Record<string, string>;
    /**
     * The surface's navigable inventory — user-reachable affordances (route links,
     * tabs, menu items, button-only nav), keyed stably. Present only when captured
     * with `inventory: true`. Diffed by the inventory guard (a removal gates), never
     * by the certification diff. See docs/inventory-guard.md.
     */
    inventory?: NavigableItem[];
    /**
     * Data-boundary requests (matching `replayUrl`) that FAILED during this capture —
     * a network error or a 4xx/5xx. Their presence means the captured state renders the
     * endpoint's FALLBACK branch, so states driven by its real responses are uncaptured
     * and unproven. Present only when the residue guard was armed (`dataResidue` set) and
     * a failure actually occurred; absent (byte-identical to before) on a clean capture.
     * Surfaced by the data-residue guard, never by the certification diff. See issue #205.
     */
    dataResidue?: DataResidueEntry[];
};
export type CaptureOptions = {
    /**
     * Selectors for nondeterministic regions (live data, embeds, ads). The
     * matching elements and their descendants are skipped entirely. Added to a
     * built-in default that skips framework/non-visual noise (`<meta>`/`<title>`/
     * `<script>`/`<style>`/… and `next-route-announcer`), so you rarely need it —
     * `stabilize` also auto-detects live regions. Use it to skip a region you know
     * is volatile without paying the settle wait for it.
     */
    ignore?: string[];
    /**
     * Harvest the surface's navigable inventory (route links, tabs, menu items,
     * button-only nav) into `StyleMap.inventory`, for the inventory guard. Off by
     * default; advisory to the certification diff — a removal gates separately.
     */
    inventory?: boolean;
    /**
     * Settle the page before capturing, and auto-exclude live regions (default
     * on). StyleProof polls the (motion-frozen) page until its computed-style map
     * stops changing — so async content that paints AFTER `go()` resolves (a
     * fetch, an SSE/WebSocket stream) is captured in its loaded state, not
     * mid-load. Any region still changing when the budget runs out is a live
     * region by definition (it mutates with no code change); its paths are
     * recorded in `StyleMap.volatile` and excluded from the diff, so a stream or
     * ticker never reads as a change — no manual `ignore` needed. Text-only churn
     * (a clock, "2m ago") never matters: the diff compares computed style, not
     * text. Pass `false` to capture the exact frame `go()` left, or `{ interval,
     * quietFor, timeout, waitForRequests }` to tune the poll cadence, the no-change
     * window that counts as settled, the budget (ms), and the network signal.
     *
     * By default the settle is **network-aware** (`waitForRequests: true`): it won't
     * settle on the brief DOM lull BEFORE a `fetch`/XHR response arrives — it holds
     * while data requests are in flight (excluding long-lived `EventSource`/WebSocket
     * streams, which never finish), so late-fetched content is captured loaded, not
     * mid-load. This is the signal a DOM-quiet window alone lacks: without it, a slow
     * backend (e.g. a dev server under CI load) settles on the loading state on one run
     * and the loaded state on the next — a self-check flake. Anything still moving at
     * `timeout` is treated as a live region. Set `waitForRequests: false` to settle on
     * DOM quiet alone.
     */
    stabilize?: boolean | {
        interval?: number;
        quietFor?: number;
        timeout?: number;
        waitForRequests?: boolean;
    };
    /**
     * Capture forced :hover/:focus/:active state deltas (default true). This is
     * the expensive layer — O(interactive elements × 3 states) with a subtree
     * evaluate each. Set false to skip it on surfaces where you don't need
     * state certification, or where the page has thousands of interactive nodes.
     */
    captureStates?: boolean;
    /**
     * Cap on interactive elements forced-state-captured per surface (default
     * 800). Beyond this the capture warns and truncates rather than hanging for
     * minutes; raise it deliberately if you need full coverage of a huge page.
     */
    maxInteractive?: number;
    /**
     * Opt-in content layer (default OFF). When true, each element's own rendered
     * text is recorded on `ElementEntry.text` so {@link diffContentMaps} can
     * surface copy changes a pure-style diff is blind to — most importantly the
     * silent ones where new or longer text overflows or clips its box. This is
     * ADVISORY: it never feeds the certification diff or its blocking counts, and
     * StyleProof stays computed-styles-first. Off by default keeps the core
     * promise (a CSS-only refactor that rewrites text is still certified
     * identical) intact for anyone who doesn't opt in. Text churn (clocks,
     * "2m ago") is auto-excluded by the same live-region settle pass that already
     * guards styles, since text now participates in change detection.
     */
    captureText?: boolean;
    /**
     * Opt-in React layer (default OFF). When true, each element records the React
     * component that rendered it (display name) and a sanitized subset of its props
     * on {@link ElementEntry.component}, read in-page from the React fiber
     * (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*`
     * on ≤16). Lets the report name `Button (variant=primary)` instead of a bare
     * `<button>`. ADVISORY — like `captureText` it never feeds the certification
     * diff or its blocking counts. Only primitive props (string/number/boolean) are
     * kept (children/handlers/objects dropped); names are mangled in minified prod
     * builds, so this is most useful against dev/non-minified output. No-op on
     * non-React pages (fiber keys absent → field omitted).
     */
    captureComponent?: boolean;
    /**
     * Advanced/internal: a getter for the count of in-flight data requests, supplied by
     * a tracker ({@link trackInflightRequests}) armed BEFORE navigation so the page's own
     * load fetches are counted by the network-aware settle. `defineStyleMapCapture`
     * wires this automatically. Omit it for a direct `captureStyleMap` call and the
     * settle arms its own tracker from capture time — which can't see a request already
     * in flight when you called it (arm one yourself before `goto` if that matters).
     */
    pendingRequests?: () => number;
    /**
     * Advanced/internal: capture-phase callback for the per-surface progress and
     * timeout layer. Called with `'settle'` when the settle wait begins and with
     * `'capture'` once the page has settled and the style reads start, so a
     * per-surface timeout can name the phase actually in flight.
     * `defineStyleMapCapture` wires this; omit it for a direct call.
     */
    onPhase?: (phase: 'settle' | 'capture') => void;
    /** Advanced/internal: metadata to persist with the capture for report context. */
    metadata?: CaptureMetadata;
};
/** True if `path` is one of `roots` or a structural descendant of one. Shared by
 *  the capture (excluding live regions) and the diff (skipping them). */
export declare function isUnder(path: string, roots: string[]): boolean;
export declare const STATE_LAYER_NAMES: readonly ["hover", "focus", "active"];
export type StateLayerName = (typeof STATE_LAYER_NAMES)[number];
/** `<stem>.hover.png` — the full-page shot with every interactive node forced. */
export declare function stateLayerScreenshotPath(stem: string, state: string): string;
/**
 * Force every interactive element into :hover, then :focus, then :active, and
 * write one full-page screenshot per state next to the rest shot. The report
 * crops those layers so a hover change is hover-versus-hover, not rest-versus-rest.
 */
export declare function captureStateLayerScreenshots(page: Page, stem: string, options?: {
    ignore?: string[];
    maxInteractive?: number;
}): Promise<string[]>;
/** Rest screenshot plus the three forced-state layers. */
export declare function captureSurfaceScreenshots(page: Page, stem: string, options?: {
    ignore?: string[];
    maxInteractive?: number;
}): Promise<void>;
/**
 * Track in-flight DATA requests on `page` so the network-aware settle can wait for
 * late-loading content to ARRIVE, not just for the DOM to go briefly quiet (the lull
 * before a response paints). Long-lived streams (EventSource/WebSocket) never finish,
 * so they're excluded — their painted state is handled by the live-region pass.
 *
 * Attach BEFORE navigation to count the page's OWN load fetches: a request already in
 * flight when you call `captureStyleMap` fired its `request` event before any listener
 * attached there, so only a tracker armed earlier (the runner does this before `go()`)
 * can see it.
 */
export declare function trackInflightRequests(page: Page): {
    pending: () => number;
    dispose: () => void;
};
/**
 * Watch the data boundary (`url`, the same `replayUrl` glob record/replay uses) for
 * requests that FAIL during capture — a network-level failure or a 4xx/5xx response.
 * A failing data request means the captured state renders that endpoint's FALLBACK
 * branch; the response-driven state is uncaptured and unproven (issue #205).
 *
 * Matches purely by listening to `requestfailed`/`response` and testing the URL against
 * the boundary glob — NOT via a `page.route`. A passive route can't be used to tag: the
 * tracker is armed before `go()`, and a route the surface itself adds in `go()` (an abort
 * fixture, the HAR replay route) runs first and never falls through to a tag route added
 * earlier, so tagged requests would be missed. Listeners see every request regardless of
 * routing, which is exactly what a residue observer needs. Arm BEFORE navigation, like
 * {@link trackInflightRequests}, so the page's own load fetches are seen; deduped per
 * `<surface>·<endpoint>` so the same failure across widths / a self-check re-run is one entry.
 *
 * ONLY failures are recorded — never a 2xx that merely wasn't fixtured: in recording mode
 * every live 2xx is legitimately recorded, so a blanket "uncontrolled" flag would fire on
 * every healthy record run (issue #205, "deliberately out of scope"). EventSource's HTTP
 * 204 is also a protocol-level terminal success, even when Chromium follows its response
 * event with `requestfailed(ERR_ABORTED)`; real aborts without that response remain residue.
 *
 * ATTRIBUTION (issue #364): the walk shares ONE page across surfaces, so a request
 * started by surface N can still be in flight when the walk hands off to surface N+1 —
 * the handoff navigation aborts it, and Chromium reports the failure while N+1's watcher
 * is armed. Which surface caught the event was a timing lottery. A failure is charged to
 * THIS surface only when the request was INITIATED inside this surface's window: its
 * `request` event fired while this watcher was armed (the watcher stamps it with the
 * current document epoch), and no cross-document main-frame commit has replaced that
 * document since (each commit advances the epoch). A leftover from a previous surface
 * (never stamped) or from a torn-down document (stale epoch) is a handoff artifact and
 * is excluded — never residue for the successor. Same-document navigations (pushState)
 * fire `framenavigated` too but issue no document request, so the epoch holds and an
 * SPA surface's own failing fetches still count.
 */
export declare function trackDataResidue(page: Page, url: string, surface: string): {
    residue: () => DataResidueEntry[];
    dispose: () => void;
};
export declare function urlMatcher(glob: string): (url: string) => boolean;
export declare function captureStyleMap(page: Page, options?: CaptureOptions): Promise<StyleMap>;
/** Write a style map to disk; gzipped when the path ends in `.gz`. */
export declare function saveStyleMap(filePath: string, map: StyleMap): void;
/** Read a style map written by {@link saveStyleMap} (`.json` or `.json.gz`). */
export declare function loadStyleMap(filePath: string): StyleMap;
/**
 * Read every surface map's navigable inventory from a capture dir, in the shape the
 * inventory audit consumes. One home for "read the inventories out of a dir", shared
 * by the diff CLI and the report (was duplicated in both).
 */
export declare function readInventories(dir: string): Array<{
    inventory?: NavigableItem[];
}>;
/**
 * Read every surface map's `dataResidue` from a capture dir, in the shape the
 * data-residue audit consumes. Lives here (not in data-residue.ts) so that module
 * stays a pure leaf — it must not import `loadStyleMap` back from this file.
 */
export declare function readResidue(dir: string): Array<{
    dataResidue?: DataResidueEntry[];
}>;
/**
 * Each captured surface key → the set of element paths it renders, unioned across
 * the given dirs (so an element present on only one side still "belongs" to the
 * surface). Feeds the shared-chrome tier, which needs to know, per surface, which
 * paths exist to tell a frame-wide change from one view's content. Shared by the
 * report and the diff CLI (both already read maps this way).
 */
export declare function surfaceElementPaths(...dirs: string[]): Map<string, Set<string>>;
/** Capture key from a map filename (`home@1280.json.gz` → `home@1280`). */
export declare function captureKeyFromMapFile(filename: string): string;
/** Every capture key present as a map file in `dir`. */
export declare function captureKeysIn(dir: string): string[];
/** Per capture key, the authoring `metadata.surfaceKey` from that map (if any). */
export declare function surfaceKeyByCaptureKey(dir: string): Map<string, string | undefined>;
/**
 * Lookup authoring `metadata.surfaceKey` across capture dirs in order (typically
 * `beforeDir`, `afterDir`). For the same capture key, a **later** dir wins when it
 * carries a defined `surfaceKey`; an undefined later entry does not clobber an
 * earlier defined value (head/after authoritative, base/before fallback).
 */
export declare function mergeSurfaceKeyLookup(...dirs: string[]): (captureKey: string) => string | undefined;
export {};