@jitsusama/agentic-harness.core 0.1.0

package/dist/web/session.d.ts

@@ -0,0 +1,1153 @@
+/**
+ * A browser session: one tab, driven by observe-then-act.
+ *
+ * observe renders the page's accessibility tree as a
+ * role-and-name outline (plus optional screenshot and
+ * readable text); act targets an element the way the model
+ * named it, role plus accessible name, disambiguated by
+ * container or ordinal, using the browser's own accessibility
+ * matching. Opaque node handles never reach the model.
+ *
+ * web_read is a one-shot over a session; the browser drive
+ * tool holds one open across tool calls. Same code path,
+ * different lifetime.
+ */
+import { type Announcement, type AxNode, type FocusHolder, type TreeScope, type WalkCapture } from "./a11y/index.js";
+import type { Comparison } from "./compare/index.js";
+import { type Animation, type BoxModel, type DelegatedListeners, type HoverReport, type Listener, type Measurement, type PseudoState, type PseudoVariant, type VisibilityVerdict } from "./element/index.js";
+import { type Divergence, type EmulationState, type NetworkRule, type ObservedEnvironment, type SavedState, type SessionStatus, type StorageSnapshot, type TabRecord, type ThrottleConditions } from "./environment/index.js";
+import { type ChordRefusal, type Point, type PointerEventStep, type TouchStep } from "./input/index.js";
+import { type Settled, type WaitCondition, type WaitOutcome } from "./wait/index.js";
+import { type A11yFinding, type BehindReport, type CapturedTarget, type ConformanceBar, type ContrastLevel, type PageBox, type PairReport, type StructureNode, type VisualNode } from "./audit/index.js";
+import { type StyleSample } from "./design/index.js";
+import { type EvalFrame, type EvalOutcome } from "./evaluate/index.js";
+import { type HeapComparison, type Hotspots, type LayerReport, type TraceCapture, type TraceProfile, type Vitals } from "./perf/index.js";
+import { type IndexedNode } from "./snapshot/index.js";
+import { type PropertyTrace, type StyleGroup } from "./styles/index.js";
+import { type Target, type TargetRefusal } from "./target/index.js";
+import { type DialogEvent, type DialogPolicy, type DownloadRecord, type LifecycleEvent, type LogEntry, type NetworkRequest, type Recorded, type SocketRecord } from "./telemetry/index.js";
+/** How a page should be laid out for reading. */
+export type PageForm = "outline" | "reading";
+/** What else to gather while inspecting an element. */
+export interface InspectOptions {
+    /** Exactly these properties instead of the curated set. */
+    readonly styles?: readonly string[];
+    /** Trace why this one property has the value it has. */
+    readonly why?: string;
+    /** Also report what is listening and what is moving. */
+    readonly behaviour?: boolean;
+    /** Hold each of these states and report what changes. */
+    readonly states?: readonly PseudoState[];
+}
+/** Everything the browser will say about one element. */
+/**
+ * What came of measuring between two elements.
+ *
+ * A target refusal is passed through with the target that earned
+ * it, so the caller can say which of the two they named was the
+ * problem rather than making them inspect both to find out.
+ */
+export type MeasureResult = {
+    readonly ok: true;
+    readonly measurement: Measurement;
+} | {
+    readonly ok: false;
+    readonly target: Target;
+    readonly refusal: TargetRefusal;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/** A font the browser really used, and how much of it. */
+export interface RenderedFont {
+    readonly family: string;
+    readonly glyphs: number;
+}
+export interface Inspection {
+    readonly node: AxNode;
+    readonly visibility: VisibilityVerdict;
+    /**
+     * What the element actually says, as opposed to what it is
+     * called. A counter reading "42" has an accessible name that
+     * mentions no number.
+     */
+    readonly text?: string;
+    /** What a field is holding, which its name never says. */
+    readonly value?: string;
+    /** Data and state attributes, which the a11y tree cannot see. */
+    readonly attributes?: Readonly<Record<string, string>>;
+    /** The fonts actually painted, as opposed to the stack asked for. */
+    readonly fonts?: readonly RenderedFont[];
+    readonly box?: BoxModel;
+    readonly styles?: readonly StyleGroup[];
+    readonly trace?: PropertyTrace;
+    readonly listeners?: readonly Listener[];
+    /**
+     * Handlers on ancestors, which events from here still reach.
+     * Delegation is how most frameworks bind, so without these an
+     * element that is listened to reads as one that is not.
+     */
+    readonly delegated?: readonly DelegatedListeners[];
+    readonly animations?: readonly Animation[];
+    readonly variants?: readonly PseudoVariant[];
+}
+/** An inspection, or the refusal that stopped it. */
+export type InspectResult = {
+    readonly ok: true;
+    readonly inspection: Inspection;
+} | {
+    readonly ok: false;
+    readonly refusal: TargetRefusal;
+};
+/** What to photograph. */
+export interface ShotOptions {
+    /** One element rather than the page. */
+    readonly target?: Target;
+    /** The whole scrollable page rather than what is on screen. */
+    readonly fullPage?: boolean;
+    /** Hold this state while capturing. */
+    readonly state?: PseudoState;
+}
+/** Where the images landed, and what had to be left out. */
+export interface Shot {
+    readonly paths: readonly string[];
+    readonly truncated: boolean;
+    readonly width: number;
+    readonly height: number;
+}
+/** A capture, or the refusal that stopped it. */
+export type ShotResult = {
+    readonly ok: true;
+    readonly shot: Shot;
+} | {
+    readonly ok: false;
+    readonly refusal: TargetRefusal;
+};
+/** The result of observing a page. */
+export interface Observation {
+    readonly url: string;
+    readonly title: string;
+    readonly outline: string;
+    /**
+     * The tree the outline was rendered from, already scoped.
+     *
+     * The rendered outline is for reading and the tree is for
+     * querying, and a caller who stores one so the other can be
+     * narrowed needs them to be the same capture. Deriving the tree
+     * again afterwards would read a page that has moved on.
+     */
+    readonly tree: AxNode;
+}
+/** An action that operates on a named element. */
+export type TargetedAction = {
+    kind: "click";
+    target: Target;
+} | {
+    kind: "type";
+    target: Target;
+    text: string;
+} | {
+    kind: "hover";
+    target: Target;
+} | {
+    kind: "focus";
+    target: Target;
+} | {
+    kind: "clear";
+    target: Target;
+} | {
+    kind: "select";
+    target: Target;
+    text: string;
+} | {
+    kind: "upload";
+    target: Target;
+    files: readonly string[];
+} | {
+    kind: "scrollTo";
+    target: Target;
+};
+/** An action to perform against the page. */
+export type PageAction = {
+    kind: "navigate";
+    url: string;
+} | TargetedAction;
+/** Why an act could not target an element, and what would work. */
+export type ActFailure = {
+    ok: false;
+    refusal: TargetRefusal;
+};
+/** An element that never became ready, and what held it up. */
+export interface Blocked {
+    readonly ready: false;
+    readonly waitedMs: number;
+    readonly blocker: string;
+}
+/** The outcome of an act call. */
+export type ActResult = {
+    ok: true;
+    waitedMs?: number;
+} | ActFailure | {
+    ok: false;
+    blocked: Blocked;
+};
+/** The outcome of reading one named branch of a page. */
+export type ObserveResult = {
+    ok: true;
+    observation: Observation;
+} | {
+    ok: false;
+    refusal: TargetRefusal;
+};
+/** How a session should behave for its whole life. */
+export interface SessionOptions {
+    /**
+     * Carry the user's own Chrome cookies into this session, so
+     * internal apps that expect a signed-in browser are drivable.
+     * Off by default: a session is a clean user unless asked.
+     */
+    readonly cookies?: boolean;
+    /**
+     * Where durable artifacts a user might want to look at (right
+     * now, comparison baselines) are written. Defaults to an
+     * adapter-neutral XDG data directory shared across whatever
+     * drives this library; an adapter with its own established
+     * convention for durable data passes its own root instead.
+     */
+    readonly dataRoot?: string;
+}
+/** Chrome cookie injection was asked for but is not set up. */
+export declare class CookieSetupNeeded extends Error {
+    constructor();
+}
+export declare class BrowserSession {
+    readonly name: string;
+    private page;
+    private cdp;
+    private readonly context;
+    private readonly options;
+    /** What every property computes to untouched, read once. */
+    private initialStyles?;
+    /** The recovery in flight, so nothing reads a tab mid-replacement. */
+    private recovery?;
+    /** The live view collaborators drive the browser through. */
+    private readonly wires;
+    /** The maps the page has declared, for authored positions. */
+    private readonly sourceMaps;
+    /** What this session pretends to be, and its keeper. */
+    private readonly emulation;
+    /** The rules and throttle this session's network answers to. */
+    private readonly shaper;
+    /** The disk side of this session: sink, stamps and ledger. */
+    private readonly artifacts;
+    /** The wait between a change and an honest reading of it. */
+    private readonly settler;
+    /** Everything this session overhears, and its buffers. */
+    private readonly telemetry;
+    private constructor();
+    /** Wall clock time of the last operation. See ready(). */
+    private usedAt;
+    /**
+     * Open a fresh session in a browser context of its own, so
+     * its cookies, storage and cache belong to it alone.
+     */
+    static open(name: string, options?: SessionOptions): Promise<BrowserSession>;
+    /** Decide how dialogs will be answered from here on. */
+    setDialogPolicy(policy: DialogPolicy): void;
+    /** How dialogs are currently answered. */
+    get dialogs(): {
+        readonly policy: DialogPolicy;
+        readonly seen: readonly DialogEvent[];
+    };
+    /** Every request the page has made. */
+    requests(): readonly NetworkRequest[];
+    /**
+     * Write a capture out as an HTTP Archive.
+     *
+     * Bodies are fetched for the requests being exported, since an
+     * archive without them answers far fewer questions than one
+     * with them, and an export is already an explicit ask.
+     */
+    exportHar(requests: readonly NetworkRequest[]): Promise<string>;
+    /**
+     * The body of one recorded reply, fetched on demand.
+     *
+     * Bodies are not captured as they stream past: most are never
+     * asked for, and holding every one would cost far more memory
+     * than the rest of the session put together. Chrome keeps them
+     * for the current document, so this asks only when asked.
+     */
+    bodyOf(requestId: string): Promise<{
+        body: string;
+        base64Encoded: boolean;
+    } | undefined>;
+    /**
+     * What the page has said, from a cursor onward.
+     *
+     * The buffer survives navigation on purpose: a message logged
+     * just before a redirect is often the one that explains it.
+     */
+    logs(since?: number): {
+        readonly entries: readonly Recorded<LogEntry>[];
+        readonly dropped: number;
+        readonly cursor: number;
+    };
+    /** Navigate the tab to a URL and wait for the network to settle. */
+    navigate(url: string): Promise<{
+        status?: number;
+        failure?: string;
+    }>;
+    /** Where the session currently is. */
+    get url(): string;
+    /**
+     * Fetch the page again.
+     *
+     * ignoreCache is the useful default for a developer, who
+     * reloads to see a change they just made. A reload that served
+     * the old file back would be the one thing it must not do.
+     */
+    reload(): Promise<{
+        failure?: string;
+    }>;
+    /**
+     * Wait for the page to stop changing, so a read that follows
+     * describes where the page ended up rather than where it was.
+     *
+     * Returns what it found instead of throwing on a page that never
+     * settles: something that animates or polls for ever is still
+     * worth reading, as long as the answer does not pretend it was
+     * final.
+     */
+    settlePage(budgetMs?: number): Promise<Settled>;
+    /** What the last settle saw, for a reader that wants to say so. */
+    get settledLast(): Settled | undefined;
+    /**
+     * Step through the history the session accumulated.
+     *
+     * Refuses rather than doing nothing at either end. Silently
+     * staying put looks identical to a page that ignored the
+     * request, and the caller then has no way to tell whether
+     * going back was possible at all.
+     *
+     * The refusal is driven by the thrown error, not by a null
+     * return. Puppeteer returns null whenever a navigation has no
+     * HTTP response, which includes about:blank and same-document
+     * moves, so reading null as failure reported a successful step
+     * back to about:blank as an impossible one. An absent entry is
+     * what throws.
+     */
+    step(direction: "back" | "forward"): Promise<{
+        readonly ok: true;
+        readonly url: string;
+    } | {
+        readonly ok: false;
+        readonly refusal: string;
+    }>;
+    /**
+     * Render the page's accessibility outline, plus url and
+     * title. A scope narrows the tree before it is rendered; with
+     * none, the whole page is read.
+     */
+    observe(scope?: TreeScope, form?: PageForm): Promise<Observation>;
+    /**
+     * Read one branch of the page, named the way the caller names
+     * anything else. Unlike a whole-page read this can fail, so
+     * it reports what would have worked instead.
+     */
+    observeWithin(target: Target, scope?: TreeScope, form?: PageForm): Promise<ObserveResult>;
+    /** Wrap a tree as an observation of where the session is. */
+    private describe;
+    /** Perform an action, resolving semantic targets against the a11y tree. */
+    act(action: PageAction): Promise<ActResult>;
+    /**
+     * Tell each frame of a stack where it was written.
+     *
+     * A frame with no map keeps its generated position rather than
+     * being dropped: half a stack is worse than a raw one.
+     */
+    resolveFrames(frames: readonly EvalFrame[]): Promise<readonly EvalFrame[]>;
+    /**
+     * Replace the dead tab with a live one.
+     *
+     * The context survives a tab crash and can still make pages,
+     * so the session keeps its identity, its cookies and every
+     * buffer it has filled; only the tab is new. Watchers have to
+     * be reinstalled because they were bound to a protocol channel
+     * that no longer answers.
+     */
+    private recover;
+    /**
+     * Point the session at a tab and make it whole again.
+     *
+     * Every watcher is bound to one tab's protocol channel, so a
+     * session that changes tabs without reinstalling them goes on
+     * answering while quietly deaf to everything the new tab does.
+     * That is the same wound a crash leaves, which is why recovering
+     * from a crash and switching tabs are one piece of code: two
+     * copies would drift, and the half that drifted would fail
+     * silently in exactly this way.
+     */
+    private bindTo;
+    /**
+     * Wait for any recovery to finish.
+     *
+     * Called before anything that touches the tab, so a read that
+     * arrives during a crash waits for the replacement instead of
+     * hanging on a renderer that is never coming back.
+     */
+    /**
+     * Wait for the replacement tab, when one is coming.
+     *
+     * The crash announcement that starts a recovery can arrive
+     * after the failure it caused, so asking whether a recovery is
+     * under way immediately gets the wrong answer. This gives the
+     * announcement its moment and then waits the recovery out,
+     * reporting whether there was one, so a caller that died for
+     * some other reason is not left waiting on a tab nobody is
+     * replacing.
+     */
+    private awaitReplacement;
+    private ready;
+    /** When this session last did anything, for the idle reaper. */
+    get lastUsedAt(): number;
+    /** Files the page has handed back. */
+    downloads(): readonly DownloadRecord[];
+    /**
+     * Record what the page's JavaScript is doing, for a while.
+     *
+     * A long task says three seconds went somewhere. This says
+     * where. The profiler is started, the page is left alone for
+     * the window asked for, and the samples are folded into time
+     * per function.
+     *
+     * Nothing is done to the page in between on purpose: whatever
+     * is being profiled has to be the page's own work, and a probe
+     * running during the window would appear in its own results.
+     */
+    profile(forMs: number): Promise<Hotspots>;
+    /**
+     * Record a trace around some work, and say what it cost.
+     *
+     * The work runs inside the recording rather than before it,
+     * because a trace only holds what happened while it was on.
+     * Measured: a timer installed before the recording starts has
+     * no install event, so its lateness cannot be explained and a
+     * fetch begun earlier has no url. Tracing after the fact is
+     * not a weaker answer, it is no answer.
+     *
+     * The work's own result is handed back whatever the recording
+     * did, so a refused permit or a protocol failure costs the
+     * caller the trace and never the action.
+     */
+    recordWhile<T>(profiles: readonly TraceProfile[], work: () => Promise<T>): Promise<{
+        readonly result: T;
+        readonly trace?: TraceCapture;
+        readonly refusal?: string;
+    }>;
+    /**
+     * Every frame id this session owns, its own and its children's.
+     *
+     * This is what separates our work from another session's in a
+     * recording that necessarily contains both.
+     */
+    private ownFrameIds;
+    /** Every websocket conversation the page has held. */
+    sockets(): readonly SocketRecord[];
+    /**
+     * Measure what the page is holding, against the last measurement.
+     *
+     * A collection is forced first unless refused, because a heap
+     * that grew means nothing while uncollected garbage is still in
+     * it. The previous reading is kept on the session so a caller
+     * can measure, do the thing they suspect, and measure again
+     * without having to carry a number between calls.
+     */
+    heap(collect?: boolean): Promise<HeapComparison>;
+    /** The previous heap reading, for the next comparison. */
+    private lastHeap?;
+    /**
+     * What the compositor is holding for this page, and why.
+     *
+     * LayerTree pushes nothing when it is enabled: the tree arrives
+     * only on layerTreeDidChange, and a page that has finished
+     * settling has no change left to report. Measured across seven
+     * candidates, a throwaway screenshot is the cheapest way to make
+     * Chrome recompose and hand the tree over, and the only one that
+     * alters nothing about the page. Scrolling moves the page,
+     * overriding device metrics disturbs an emulation the caller may
+     * have set, and toggling a style writes to the DOM.
+     *
+     * The domain goes off again afterwards, so a read leaves no
+     * instrumentation running behind it.
+     */
+    /**
+     * Judge text against the background actually behind its glyphs.
+     *
+     * For the case axe hands back as needing a person: text over a
+     * gradient, a photograph, or anything else with no single
+     * background colour. Two shots of the same region, the second with
+     * the text hidden, give both the glyph mask and what lies under it.
+     *
+     * Hiding the text is a paint-only change, so nothing moves between
+     * the shots and the subtraction stays aligned. The inline style is
+     * put back in a finally, including the case where it had one of its
+     * own to begin with.
+     */
+    contrastBehind(target: Target, bar?: ContrastLevel): Promise<{
+        ok: true;
+        report: BehindReport;
+    } | {
+        ok: false;
+        refusal: TargetRefusal;
+    }>;
+    /**
+     * Judge the contrast between two elements the caller named.
+     *
+     * Distinct from contrastBehind, which subtracts pixels to read the
+     * background under one element's glyphs. This compares two
+     * elements' stated colours, which is the only way to ask about a
+     * boundary: an icon against its card, a border against the page.
+     * Both sides are read from the computed style rather than the
+     * screen, so nothing is captured and nothing moves.
+     */
+    contrastPair(one: Target, other: Target, bar?: ContrastLevel): Promise<{
+        ok: true;
+        report: PairReport;
+    } | {
+        ok: false;
+        target: Target;
+        refusal: TargetRefusal;
+    }>;
+    /** What one side of a contrast pairing paints. */
+    private paintedSide;
+    /**
+     * Make an element's own text stop painting, and put it back.
+     *
+     * Only colour and shadow are touched, because neither affects
+     * layout: the glyphs still occupy the same pixels, they simply
+     * leave no mark on them.
+     */
+    private hideText;
+    layers(): Promise<LayerReport>;
+    /**
+     * What the page does on hover, and whether focus does it too.
+     *
+     * Two halves, because either alone lies. The stylesheets say
+     * which elements might hover, cheaply and in one round trip, but
+     * a declared rule the cascade beat changes nothing a person can
+     * see. So the scan only proposes candidates, and each one is then
+     * held in hover and in focus and read, which is the only account
+     * of what actually happens.
+     *
+     * Bounded because there is a round trip per candidate, measured
+     * at roughly 9ms for the pair of states.
+     */
+    hovers(limit?: number): Promise<HoverReport>;
+    /** Which selectors carry a hover, as the page's own sheets say. */
+    private scanForHover;
+    /** Backend ids matching a selector, or none if it will not parse. */
+    private nodesMatching;
+    /** Hold hover, then focus, and read what each changed. */
+    private measureHover;
+    /** Why Chrome composited one layer, or nothing if it will not say. */
+    private reasonsFor;
+    /** A short name for the element behind a layer. */
+    private nameOfNode;
+    /** Give the compositor a moment to finish reporting. */
+    private settleLayers;
+    /** Socket events dropped to stay within the buffer's budget. */
+    get socketFramesDropped(): number;
+    /** Where the page has been. */
+    get history(): readonly LifecycleEvent[];
+    /**
+     * Put the emulation back exactly as it was.
+     *
+     * emulate merges, which is right for a caller adding one
+     * condition and wrong for anything that has to undo itself: a
+     * merge cannot clear a field, so a sweep that widened the
+     * viewport could never restore a session that had none. This
+     * replaces the state wholesale.
+     */
+    restoreEmulation(state: EmulationState): Promise<void>;
+    /**
+     * Pretend to be a different visitor, then report what the page
+     * actually experiences.
+     *
+     * The intent is kept whole and re-applied in full, because
+     * Chrome's media emulation forgets anything a call omits, so
+     * asking for reduced motion after asking for dark mode would
+     * otherwise turn the dark mode back off.
+     */
+    emulate(change?: EmulationState, 
+    /** Overrides to take off, which an absent key cannot express. */
+    clear?: readonly (keyof EmulationState)[]): Promise<{
+        asked: EmulationState;
+        observed: ObservedEnvironment;
+        gaps: readonly Divergence[];
+    }>;
+    /** What this session has asked the browser to pretend. */
+    get emulated(): EmulationState;
+    /**
+     * Read what the page has kept.
+     *
+     * A store that cannot be read says why rather than coming
+     * back empty, since an empty store and an unreadable one lead
+     * to opposite conclusions.
+     */
+    storage(wanted: {
+        local?: boolean;
+        session?: boolean;
+        cookies?: boolean;
+        clipboard?: boolean;
+    }): Promise<StorageSnapshot>;
+    /** One of the two DOM stores, keyed by this frame's origin. */
+    private domStorage;
+    /** Put a value into one of the DOM stores. */
+    setStored(isLocalStorage: boolean, key: string, value: string): Promise<void>;
+    /**
+     * Measure the space between two elements.
+     *
+     * The border box is the one measured, because that is the edge
+     * a designer sees and points at. Margins are the space itself,
+     * so measuring between margin boxes would report the gap that
+     * remains after the gap, which is nearly always zero.
+     */
+    measure(a: Target, b: Target): Promise<MeasureResult>;
+    /**
+     * Every tab this session's context is holding open.
+     *
+     * A page that opens another one is doing something ordinary: a
+     * target of _blank, a sign-in or a payment handed to a second
+     * window. Until this existed the new tab was real, live and
+     * entirely invisible, and the click that made it looked like a
+     * click that did nothing.
+     */
+    tabs(): Promise<readonly TabRecord[]>;
+    /**
+     * Drive a different tab from now on.
+     *
+     * The tab left behind is not closed. A sign-in that opened a
+     * second window usually wants the first one back afterwards, and
+     * closing it would make switching a one-way trip.
+     */
+    switchTab(index: number): Promise<TabRecord | {
+        refusal: string;
+    }>;
+    /**
+     * Keep everything that makes this session signed in.
+     *
+     * Cookies and the two DOM stores together, because being logged
+     * in is rarely all in one of them: a session cookie and a token
+     * in local storage is the ordinary arrangement, and saving half
+     * of it produces a state that restores without signing anyone
+     * in.
+     */
+    saveState(): Promise<SavedState>;
+    /**
+     * Wear a state saved earlier, and report exactly what landed.
+     *
+     * Cookies go to the browser, so they apply whatever page is
+     * open. The DOM stores are scoped to an origin, so they can only
+     * be written while the session is on the origin they came from,
+     * and the answer says when they were not rather than counting
+     * them as restored. A caller who is told they are signed in and
+     * is not will blame the site.
+     */
+    loadState(state: SavedState): Promise<{
+        cookies: number;
+        local: number;
+        session: number;
+        wrongOrigin?: string;
+    }>;
+    /** Empty the stores named, and only those. */
+    clearStorage(wanted: {
+        local?: boolean;
+        session?: boolean;
+        cookies?: boolean;
+    }): Promise<void>;
+    /**
+     * Read the clipboard.
+     *
+     * Chrome refuses this unless the permission is granted against
+     * the browser context, not merely the origin, and unless the
+     * read is attributed to a user gesture. Both were measured;
+     * either alone still gets a refusal.
+     */
+    private clipboard;
+    /** Put text on the clipboard. */
+    writeClipboard(text: string): Promise<void>;
+    /** Ask for clipboard access against this context. */
+    private grantClipboard;
+    /** The origin the current page's stores are keyed by. */
+    private origin;
+    /**
+     * Bend the network: mock a reply, block a request, slow it all
+     * down, or stop pretending.
+     *
+     * Interception is only attached while there is a rule to
+     * apply. Every paused request has to be answered or the page
+     * waits on it forever, so an interceptor with nothing to say
+     * is a liability rather than a neutral bystander.
+     */
+    shape(change: {
+        rules?: readonly NetworkRule[];
+        /** Conditions, or the name of a profile such as slow-3g. */
+        throttle?: ThrottleConditions | string;
+        clear?: boolean;
+    }): Promise<{
+        rules: readonly NetworkRule[];
+        throttle: ThrottleConditions | undefined;
+    }>;
+    /**
+     * Press a chord, or a sequence of them.
+     *
+     * Dispatch goes through the driver's keyboard rather than the
+     * protocol directly, because the driver owns the layout table
+     * that turns a key name into a code, a virtual key number and
+     * the text it produces. Keeping a second opinion about that
+     * would be a second thing to be wrong about.
+     */
+    press(keys: string): Promise<{
+        pressed: readonly string[];
+    } | {
+        refusal: ChordRefusal;
+    }>;
+    /** Send raw text as keystrokes, wherever focus happens to be. */
+    typeRaw(text: string): Promise<void>;
+    /** Dispatch a composed mouse gesture. */
+    pointerGesture(steps: readonly PointerEventStep[]): Promise<void>;
+    /** Scroll by wheel, which is not the same as scrolling by script. */
+    wheel(at: Point, byX: number, byY: number): Promise<void>;
+    /**
+     * Dispatch a composed touch gesture.
+     *
+     * Touch events reach the page whether or not touch emulation
+     * is on, so this never refuses. What emulation changes is what
+     * the page believes about itself: maxTouchPoints and the
+     * coarse-pointer media query. A page that decides at load time
+     * whether to attach touch handlers will not have attached any,
+     * and the gesture lands on nothing, so the caller is told
+     * rather than stopped.
+     */
+    touchGesture(steps: readonly TouchStep[]): Promise<void>;
+    /**
+     * Walk the page with the Tab key and report what happened.
+     *
+     * This is one of the two reads that deliberately change the
+     * page, since there is no way to learn where focus goes
+     * without moving it. Focus is put back afterwards and the
+     * result says so.
+     *
+     * The walk runs to twice the number of focusable things plus a
+     * little, which is enough for a healthy page to come round
+     * twice and for a trap to show its cycle. Stopping sooner
+     * would report a trap as a short page.
+     */
+    keyboardWalk(maxStops?: number): Promise<WalkCapture>;
+    /** Which way the document says it reads. */
+    private readingDirection;
+    /**
+     * The whole page flattened, frames and shadow content
+     * included.
+     *
+     * The style properties have to be named up front because the
+     * protocol returns their values as a bare array positioned
+     * against the request. Asking for a handful keeps the snapshot
+     * small; asking for none still gives geometry and structure.
+     */
+    snapshot(styleProperties?: readonly string[]): Promise<readonly IndexedNode[]>;
+    /**
+     * Run an expression in the page and describe what came back.
+     *
+     * The value is serialized inside the page rather than by the
+     * protocol, because the protocol does not decline politely: a
+     * circular object rejects the whole call with "object
+     * reference chain is too long", losing the evaluation and any
+     * account of it together.
+     *
+     * The protocol can still fail for its own reasons, so that is
+     * caught too and returned as a refusal rather than thrown. An
+     * expression that kills the session is not a useful tool.
+     */
+    evaluate(expression: string): Promise<EvalOutcome>;
+    /**
+     * Run axe-core against the page and read back its findings.
+     *
+     * axe is injected fresh on every call rather than kept across
+     * navigations. It is half a megabyte, but a navigation clears
+     * the world, and an audit that silently reported nothing
+     * because the library went away with the last page would be
+     * worse than a slow one.
+     *
+     * Only violations and incomplete results are asked for. Passes
+     * and inapplicable rules together outweigh them by an order of
+     * magnitude and answer a question nobody asks.
+     *
+     * The experimental rules are switched on. axe leaves them off,
+     * and five of them carry real WCAG criteria, so leaving them
+     * off means 2.5.3 (label in name) is never checked and 1.3.1
+     * is checked less thoroughly than it looks. An accessibility
+     * reviewer reported label in name as missing, and it was, in
+     * the sense that matters: the rule sat in the bundle unused.
+     * Their findings are reported as needing a person rather than
+     * as failures, since axe's own doubt travels with them.
+     */
+    audit(bar?: ConformanceBar): Promise<readonly A11yFinding[]>;
+    /**
+     * The page as the structural rules need to see it.
+     *
+     * Two accounts from the browser, joined on the backend node id
+     * they share: the snapshot for attributes and layout, the
+     * accessibility tree for roles and names. Neither carries
+     * both, and every structural rule needs both.
+     */
+    /**
+     * What holds focus at this moment, moving nothing.
+     *
+     * The keyboard walk answers what a whole page does; this answers
+     * where focus is right now, which is the question between
+     * actions. It reads rather than presses, so it can be asked after
+     * a click or a navigation without disturbing what it reports.
+     */
+    focusHolder(): Promise<FocusHolder | undefined>;
+    structure(): Promise<readonly StructureNode[]>;
+    /**
+     * What the layout actually did, as the browser measured it.
+     *
+     * Read in one page-side pass rather than a protocol call per
+     * element: a page of any size would otherwise cost thousands
+     * of round trips to answer one question.
+     */
+    /**
+     * Every pointer target on the page, with the facts WCAG 2.5.8
+     * needs to judge its size.
+     *
+     * Separate from layout() because the two ask different
+     * questions: layout wants everything drawn, this wants only
+     * what a finger has to hit, plus the two exceptions the
+     * criterion turns on.
+     */
+    targets(): Promise<readonly CapturedTarget[]>;
+    layout(): Promise<{
+        readonly nodes: readonly VisualNode[];
+        readonly viewport: PageBox;
+    }>;
+    /**
+     * What the page is built from, sampled element by element.
+     *
+     * Read in one page-side pass, and filtered there rather than
+     * here: an inherited value is not a decision, and carrying
+     * every element's inherited colour back only to discard it
+     * would be most of the payload.
+     */
+    styleSamples(): Promise<readonly StyleSample[]>;
+    /**
+     * Install the performance observers ahead of every page.
+     *
+     * Largest contentful paint and layout shift are events rather
+     * than state, so an observer registered after a page loads has
+     * missed them. The buffered flag recovers the timings but not
+     * the element that painted or the nodes that moved, which is
+     * the half worth having, so this goes in through the hook that
+     * runs before the document does.
+     */
+    private watchVitals;
+    /** What the current page cost to show. */
+    vitals(): Promise<Vitals>;
+    /** Run a page-side source string and read back its value. */
+    private evaluateJson;
+    /** Whether the page believes it is being touched. */
+    get touchEmulated(): boolean;
+    /**
+     * Wait for the page to reach a state, and say what happened.
+     *
+     * The timeout is a real answer rather than an error. A page
+     * that never reaches the state is the finding, so the outcome
+     * carries what was true instead.
+     */
+    waitFor(condition: WaitCondition, timeoutMs?: number): Promise<WaitOutcome>;
+    /** Look once: is the condition true right now? */
+    private check;
+    /**
+     * Everything this session has accumulated, in one reading.
+     *
+     * Emulation, interception and dialog policy all change what
+     * every other reading means, and none of them is visible in
+     * those readings, so they are gathered here.
+     */
+    status(): Promise<SessionStatus>;
+    /** How the network is currently being bent. */
+    get shaping(): {
+        rules: readonly NetworkRule[];
+        throttle: ThrottleConditions | undefined;
+    };
+    /**
+     * What the page has announced since a cursor, with the cursor
+     * to read from next time and how many were dropped.
+     */
+    heard(since?: number): Promise<{
+        entries: readonly Recorded<Announcement>[];
+        cursor: number;
+        dropped: number;
+    }>;
+    /** Close the tab and the context holding its state. */
+    close(): Promise<void>;
+    /**
+     * Everything worth knowing about one element.
+     *
+     * Each fact is asked of the browser rather than worked out
+     * here: the box from the layout engine, the occluder from a
+     * hit test, the styles from the cascade, the announcement from
+     * the accessibility tree.
+     */
+    inspect(target: Target, options?: InspectOptions): Promise<InspectResult>;
+    /**
+     * Which fonts the browser actually painted with.
+     *
+     * A computed style reports the stack that was asked for, not
+     * what was used. "SF Pro, Helvetica, sans-serif" reads the same
+     * whether the first one loaded or the page quietly fell back to
+     * the third, which is most of the answer to why a screenshot
+     * from one machine does not match another.
+     */
+    private fontsOf;
+    /**
+     * The element's own words, and the attributes it carries.
+     *
+     * The accessible name answers what a control is called, which
+     * is a different question from what it says. A counter reading
+     * "42", a status reading "3 items updated" and an input holding
+     * a typed email all have names that say none of that, so
+     * asserting on them meant dropping to a raw evaluate. Data
+     * attributes are here for the same reason: teams hang test
+     * state on them, and the accessibility tree cannot see them.
+     */
+    private contentOf;
+    /**
+     * A handle on the element inside this session.
+     *
+     * Object identifiers belong to the protocol session that
+     * minted them, so puppeteer's own handles are unusable here.
+     * A backend node id is the identity both sides agree on.
+     */
+    private objectFor;
+    /**
+     * Swap a text node for the element that paints it.
+     *
+     * A `StaticText` target resolves to a text node, which is right
+     * for reading its box and wrong for everything that touches
+     * style. Returns the original handle when it is already an
+     * element, so callers can promote unconditionally.
+     */
+    private paintingElement;
+    /** Let go of a handle, whether or not the page still has it. */
+    private release;
+    /** Gather every fact about an element the browser will give. */
+    private inspectNode;
+    /**
+     * Photograph the page, or one element of it.
+     *
+     * Images never come back inline: a screenshot is far larger
+     * than any response budget and would crowd out the reading it
+     * was meant to illustrate. They go to the session's bundle
+     * directory and the answer carries the paths.
+     *
+     * A full-page capture is tiled, because a long page makes an
+     * image taller than a model will accept. The tiling and its
+     * ceiling are the ones web_read already uses, so a page reads
+     * the same either way.
+     */
+    shoot(options?: ShotOptions): Promise<ShotResult>;
+    /** Force or release a state for the duration of a capture. */
+    private holdState;
+    /** Take the picture and write it out. */
+    private capture;
+    /**
+     * Compare the page now against a baseline of it, or record
+     * one when there is none.
+     *
+     * A missing baseline is not a failure. The first run of any
+     * comparison has nothing to compare against, and refusing
+     * would make the tool need a setup step it can perform itself.
+     *
+     * The elements are read after the shot rather than before, so
+     * a region is attributed against the layout that was actually
+     * photographed.
+     */
+    compareToBaseline(label: string, options?: {
+        readonly update?: boolean;
+        readonly threshold?: number;
+    }): Promise<{
+        readonly comparison: Comparison | undefined;
+        readonly recorded?: string;
+        readonly artifacts: readonly string[];
+    }>;
+    /**
+     * Where this session's baselines live.
+     *
+     * Under the data directory, not the bundle root. This used to
+     * sit at BUNDLE_ROOT/baselines, which the bundle reaper treats
+     * as an ownerless directory (the name is not a pid) and deletes
+     * once it is six hours old. Writing a baseline touches the
+     * session subdirectory rather than its parent, so the parent's
+     * age kept climbing and a stable set of baselines was reaped on
+     * a timer. The next comparison then found nothing, recorded the
+     * current page as truth and reported a warning, which is data
+     * loss wearing a first run's clothes.
+     *
+     * A baseline is a durable artifact the user asked for and may
+     * want to look at, which is what dataDir is for.
+     */
+    private baselineDir;
+    /**
+     * What a baseline was taken under, stored beside the image.
+     *
+     * Without this a comparison cannot tell a regression from a
+     * change of subject: record on one page, navigate to another,
+     * and the diff reports confident failures attributed to the
+     * second page's elements. The size check alone cannot see it,
+     * because two pages at one viewport are the same size.
+     */
+    private provenance;
+    /** Carry out an action against an element judged ready. */
+    private perform;
+    /**
+     * Wait until an element can actually be acted on.
+     *
+     * A click on an element that is not ready does nothing and
+     * says nothing, leaving a caller believing the page was acted
+     * on. So readiness is established first, and when the budget
+     * runs out the condition still in the way is reported rather
+     * than the action being attempted regardless.
+     */
+    private awaitReady;
+    /** One look at whether an element is ready. */
+    private readinessOf;
+    /**
+     * Whether something is painted over the element's centre.
+     *
+     * Only the centre, unlike a full inspection: this runs on
+     * every poll, and the centre is where a click is aimed.
+     */
+    private coveredAtCentre;
+    /** What is listening on the element. */
+    private listenersOf;
+    /**
+     * What is listening further up, which events from here reach.
+     *
+     * The protocol reads listeners off one object at a time and can
+     * walk down into children but not up, so the ancestors are
+     * collected in the page and each one asked separately. A live
+     * button whose click was handled on the body reported nothing
+     * listening, which is the answer that most invites the wrong
+     * conclusion from an inspection meant to explain a dead click.
+     */
+    private delegatedTo;
+    /** Ask each ancestor in the array what is listening on it. */
+    private listenersUp;
+    /** What is moving on the element. */
+    private animationsOf;
+    /**
+     * How the element looks in each state, against how it looks at
+     * rest.
+     *
+     * The forced state is always released afterwards, including
+     * when a reading throws part way through. Leaving a page stuck
+     * in a forced hover would quietly corrupt every later
+     * observation of it.
+     */
+    private variantsOf;
+    /**
+     * Let whatever the forced state started finish before reading.
+     *
+     * Without this the reading catches a transition at its resting
+     * values and reports that the state changes nothing, which is
+     * exactly backwards.
+     */
+    private settleForcedState;
+    /** The front-end node id, which the CSS agent works in. */
+    private frontendNodeFor;
+    /** The element's four boxes, or nothing when it has none. */
+    private boxOf;
+    /** Every computed property of the element, as the browser has it. */
+    private stylesOf;
+    /**
+     * What every property computes to untouched, read once per
+     * session. These decide which values were actually chosen.
+     */
+    private initials;
+    /** Why one property has the value it has. */
+    private traceOf;
+    /**
+     * Tell each declaration in a trace where it was written.
+     *
+     * A build step that rewrote the CSS makes the reported line
+     * useless in the same way a minified stack frame is: it names
+     * a file nobody edits. The winner is usually the declaration
+     * somebody wants to go and change, so it is the one that most
+     * needs an address that exists.
+     */
+    private authorTrace;
+    /** The area a person can currently see. */
+    private viewport;
+    /**
+     * How far the page has been scrolled, in CSS pixels.
+     *
+     * Read from the browser's own layout metrics rather than from the
+     * page, so a capture does not have to run script to be correct.
+     * Answers zero when the metrics are unavailable, which is what the
+     * offset was assumed to be before it was asked for at all.
+     */
+    private scrollOffset;
+    /**
+     * What is painted over the element, if anything.
+     *
+     * The centre and the corners, since a full inspection should
+     * report an element clipped at one edge. Anything the element
+     * contains counts as itself, since a click there still reaches
+     * it.
+     */
+    private occluderOf;
+    /**
+     * Who receives a click, when it is not us.
+     *
+     * The point is chosen inside the page rather than out here. Both
+     * halves of the question used to be asked separately, the box
+     * from the box model and the hit from `DOM.getNodeForLocation`,
+     * and they disagree by the scroll offset, so anything the driver
+     * had to scroll to was reported as covered by whatever sat at
+     * the wrong point.
+     */
+    private hitTest;
+    private resolve;
+    /**
+     * The backend node id behind a handle, or undefined if it has gone.
+     *
+     * This asks puppeteer rather than sending DOM.describeNode ourselves
+     * because a remote object id is scoped to the session that minted it,
+     * and these handles were minted by puppeteer's session, not ours.
+     * Resolving them through this.cdp fails for every handle, which reads
+     * as "no candidate matched" and refuses every act.
+     */
+    private backendIdOf;
+    private axTree;
+    /**
+     * Each same-origin child frame's tree, and what owns it.
+     *
+     * Chrome answers for one frame at a time, so a page built from
+     * embeds read as a row of empty boxes: the outline stopped at
+     * the Iframe node and said nothing about stopping. Everything
+     * downstream inherited that, so a keyboard walk skipped an
+     * embedded form and an audit passed a page it had not seen.
+     *
+     * Breadth-first, parents before children, because the splice
+     * attaches each frame to an owner that must already be in the
+     * tree by the time its turn comes.
+     *
+     * A frame that cannot be read is left out rather than reported
+     * as empty. Cross-origin frames are the common case and are a
+     * real limit, not a fault; the count of what could not be read
+     * belongs to the callers that already report it.
+     */
+    private frameTrees;
+}