@jitsusama/agentic-harness.core 0.1.0

package/dist/web/environment/shaping.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Bending the network under the page.
+ *
+ * Two different needs share this module. Mocking and blocking
+ * answer "what does this page do when that request returns
+ * something else, or nothing at all", which is the only honest
+ * way to see an error path that a healthy server never
+ * produces. Throttling answers "what is this like on a train".
+ */
+/** What to do with a request that matches. */
+export type ShapeAction = "mock" | "block";
+/** One instruction about a family of requests. */
+export interface NetworkRule {
+    readonly pattern: string;
+    readonly action: ShapeAction;
+    /** For a mock: the status to answer with. Defaults to 200. */
+    readonly status?: number;
+    /** For a mock: the body to answer with. */
+    readonly body?: string;
+    /** For a mock: what the body is. */
+    readonly contentType?: string;
+    /** For a block: the reason Chrome should report. */
+    readonly reason?: string;
+}
+/** How fast the network should pretend to be. */
+export interface ThrottleConditions {
+    readonly offline: boolean;
+    /** Bytes per second down, 0 meaning no limit. */
+    readonly download: number;
+    /** Bytes per second up, 0 meaning no limit. */
+    readonly upload: number;
+    /** Round trip milliseconds added to every request. */
+    readonly latency: number;
+}
+/**
+ * The profiles Chrome's own devtools ships.
+ *
+ * Written as the expressions from its source rather than as
+ * the products, so the derivation stays checkable: a datasheet
+ * bandwidth, a loss factor, and a round trip multiplied to
+ * account for the several trips a real request makes. Chrome
+ * renamed "Fast 3G" to "Slow 4G" in 2024, and both names are
+ * accepted so neither vocabulary is wrong here.
+ */
+export declare const THROTTLE_PROFILES: Readonly<Record<string, ThrottleConditions>>;
+/** A named profile, under either the current or the old name. */
+export declare function throttleProfile(name: string): ThrottleConditions | undefined;
+/** Every profile name that can be asked for. */
+export declare function throttleNames(): readonly string[];
+/**
+ * The conditions a caller means, named or spelled out.
+ *
+ * A profile name is the natural thing to write and was the one
+ * thing that did not work: passed a name, the library read the
+ * fields it wanted off a string, found nothing, and shaped
+ * nothing. A navigation then came back 200 while the caller
+ * believed the network was offline, which is the worst kind of
+ * quiet failure because the test appears to have run.
+ *
+ * Throws on a name that is not a profile. A caller who names a
+ * network that does not exist cannot be given one, and continuing
+ * at full speed would misreport whatever they measure next.
+ */
+export declare function resolveThrottle(value: ThrottleConditions | string): ThrottleConditions;
+/**
+ * Whether a url answers to a pattern.
+ *
+ * Patterns are globs because that is what the protocol's own
+ * request interception uses, so one vocabulary covers both what
+ * we match locally and what we ask Chrome to intercept.
+ *
+ * Both arguments are strings and transposing them is silent, so
+ * they are named rather than positional. That is not a
+ * hypothetical: the first caller outside this file passed them
+ * the wrong way round and got a confident false.
+ */
+export declare function matchesPattern({ pattern, url, }: {
+    pattern: string;
+    url: string;
+}): boolean;
+/**
+ * The rule that governs a url, or none.
+ *
+ * First match wins, in the order the rules were given, so a
+ * caller can put a specific exception ahead of a general rule
+ * and have it hold.
+ */
+export declare function ruleFor(rules: readonly NetworkRule[], url: string): NetworkRule | undefined;
+/** What the network is currently being made to do. */
+export declare function renderShaping(rules: readonly NetworkRule[], throttle: ThrottleConditions | undefined): string;

package/dist/web/environment/shaping.js

@@ -0,0 +1,141 @@
+/**
+ * Bending the network under the page.
+ *
+ * Two different needs share this module. Mocking and blocking
+ * answer "what does this page do when that request returns
+ * something else, or nothing at all", which is the only honest
+ * way to see an error path that a healthy server never
+ * produces. Throttling answers "what is this like on a train".
+ */
+/**
+ * The profiles Chrome's own devtools ships.
+ *
+ * Written as the expressions from its source rather than as
+ * the products, so the derivation stays checkable: a datasheet
+ * bandwidth, a loss factor, and a round trip multiplied to
+ * account for the several trips a real request makes. Chrome
+ * renamed "Fast 3G" to "Slow 4G" in 2024, and both names are
+ * accepted so neither vocabulary is wrong here.
+ */
+export const THROTTLE_PROFILES = {
+    offline: { offline: true, download: 0, upload: 0, latency: 0 },
+    "slow-3g": {
+        offline: false,
+        download: ((500 * 1000) / 8) * 0.8,
+        upload: ((500 * 1000) / 8) * 0.8,
+        latency: 400 * 5,
+    },
+    "slow-4g": {
+        offline: false,
+        download: ((1.6 * 1000 * 1000) / 8) * 0.9,
+        upload: ((750 * 1000) / 8) * 0.9,
+        latency: 150 * 3.75,
+    },
+    "fast-4g": {
+        offline: false,
+        download: ((9 * 1000 * 1000) / 8) * 0.9,
+        upload: ((1.5 * 1000 * 1000) / 8) * 0.9,
+        latency: 60 * 2.75,
+    },
+    none: { offline: false, download: 0, upload: 0, latency: 0 },
+};
+/** The name Chrome used before 2024, kept so it still works. */
+const PROFILE_ALIASES = {
+    "fast-3g": "slow-4g",
+    "3g": "slow-3g",
+    "4g": "fast-4g",
+};
+/** A named profile, under either the current or the old name. */
+export function throttleProfile(name) {
+    const key = name.toLowerCase();
+    return THROTTLE_PROFILES[PROFILE_ALIASES[key] ?? key];
+}
+/** Every profile name that can be asked for. */
+export function throttleNames() {
+    return Object.keys(THROTTLE_PROFILES);
+}
+/**
+ * The conditions a caller means, named or spelled out.
+ *
+ * A profile name is the natural thing to write and was the one
+ * thing that did not work: passed a name, the library read the
+ * fields it wanted off a string, found nothing, and shaped
+ * nothing. A navigation then came back 200 while the caller
+ * believed the network was offline, which is the worst kind of
+ * quiet failure because the test appears to have run.
+ *
+ * Throws on a name that is not a profile. A caller who names a
+ * network that does not exist cannot be given one, and continuing
+ * at full speed would misreport whatever they measure next.
+ */
+export function resolveThrottle(value) {
+    if (typeof value !== "string")
+        return value;
+    const profile = throttleProfile(value);
+    if (!profile) {
+        throw new Error(`No network profile named '${value}'. ` +
+            `Try one of ${throttleNames().join(", ")}, or give the ` +
+            "conditions directly.");
+    }
+    return profile;
+}
+/**
+ * Whether a url answers to a pattern.
+ *
+ * Patterns are globs because that is what the protocol's own
+ * request interception uses, so one vocabulary covers both what
+ * we match locally and what we ask Chrome to intercept.
+ *
+ * Both arguments are strings and transposing them is silent, so
+ * they are named rather than positional. That is not a
+ * hypothetical: the first caller outside this file passed them
+ * the wrong way round and got a confident false.
+ */
+export function matchesPattern({ pattern, url, }) {
+    if (pattern === "*")
+        return true;
+    const expression = pattern
+        // Escape everything a regular expression would read, then
+        // give the star back its meaning.
+        .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*");
+    return new RegExp(`^${expression}$`).test(url) || url.includes(pattern);
+}
+/**
+ * The rule that governs a url, or none.
+ *
+ * First match wins, in the order the rules were given, so a
+ * caller can put a specific exception ahead of a general rule
+ * and have it hold.
+ */
+export function ruleFor(rules, url) {
+    return rules.find((rule) => matchesPattern({ pattern: rule.pattern, url }));
+}
+/** What the network is currently being made to do. */
+export function renderShaping(rules, throttle) {
+    const lines = [];
+    if (throttle?.offline) {
+        lines.push("The network is offline.");
+    }
+    else if (throttle && (throttle.latency > 0 || throttle.download > 0)) {
+        lines.push(`Throttled to ${Math.round(throttle.download / 1024)} KB/s down, ` +
+            `${Math.round(throttle.upload / 1024)} KB/s up, ` +
+            `${Math.round(throttle.latency)}ms latency.`);
+    }
+    else {
+        lines.push("The network is unshaped.");
+    }
+    if (rules.length === 0) {
+        lines.push("No requests are being mocked or blocked.");
+    }
+    else {
+        lines.push("", "Rules, first match winning:");
+        for (const rule of rules) {
+            lines.push(rule.action === "block"
+                ? `  block  ${rule.pattern}`
+                : `  mock   ${rule.pattern} -> ${rule.status ?? 200}` +
+                    `${rule.contentType ? ` ${rule.contentType}` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/web/environment/status.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Where a session stands.
+ *
+ * Everything a session accumulates is invisible until asked
+ * for: what it is pretending to be, what it has intercepted,
+ * how much it has recorded, and how far each buffer has been
+ * read. Coming back to a session after doing something else and
+ * having to guess at any of that is how a reading gets
+ * misattributed to the wrong page.
+ */
+import type { DialogPolicy, LifecycleEvent } from "../telemetry/index.js";
+import type { Divergence, EmulationState } from "./emulation.js";
+import type { NetworkRule, ThrottleConditions } from "./shaping.js";
+/** Everything worth knowing about a session at a glance. */
+export interface SessionStatus {
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly emulation: EmulationState;
+    /** Where the page disagrees with what is being emulated. */
+    readonly gaps?: readonly Divergence[];
+    readonly rules: readonly NetworkRule[];
+    readonly throttle?: ThrottleConditions;
+    readonly dialogPolicy: DialogPolicy;
+    readonly dialogsSeen: number;
+    readonly logs: {
+        readonly count: number;
+        readonly cursor: number;
+    };
+    readonly announcements: {
+        readonly count: number;
+        readonly cursor: number;
+    };
+    readonly requests: {
+        readonly count: number;
+        readonly failed: number;
+    };
+    readonly history: readonly LifecycleEvent[];
+    readonly artifacts: readonly string[];
+    /**
+     * A trace being recorded anywhere in the browser.
+     *
+     * Reported by every session rather than only the one that
+     * started it, because tracing instruments every page and a
+     * reader wondering why theirs is slow should find the reason
+     * here instead of hunting for it.
+     */
+    readonly recording?: string;
+}
+/** The session, in one reading. */
+export declare function renderStatus(status: SessionStatus): string;

package/dist/web/environment/status.js

@@ -0,0 +1,109 @@
+/**
+ * Where a session stands.
+ *
+ * Everything a session accumulates is invisible until asked
+ * for: what it is pretending to be, what it has intercepted,
+ * how much it has recorded, and how far each buffer has been
+ * read. Coming back to a session after doing something else and
+ * having to guess at any of that is how a reading gets
+ * misattributed to the wrong page.
+ */
+/** How many recent navigations are worth recalling. */
+const RECENT_HISTORY = 5;
+/** The session, in one reading. */
+export function renderStatus(status) {
+    const lines = [
+        `Session '${status.name}'`,
+        `  at ${status.url || "nowhere yet"}`,
+        ...(status.title ? [`  titled ${status.title}`] : []),
+        "",
+        `  ${status.logs.count} log entries, cursor ${status.logs.cursor}`,
+        `  ${status.requests.count} requests${status.requests.failed > 0 ? `, ${status.requests.failed} failed` : ""}`,
+        `  ${status.announcements.count} announcements, cursor ` +
+            `${status.announcements.cursor}`,
+    ];
+    const pretending = describeEmulation(status.emulation);
+    if (pretending)
+        lines.push("", `  pretending: ${pretending}`);
+    // Only ever claimed with the page's agreement.
+    //
+    // An override sent to a renderer that a navigation then replaced
+    // goes nowhere, and Chrome gives no signal when that happens. It
+    // is now applied again on arrival and checked against the page,
+    // which fixes nearly every case, but a browser that loses it
+    // anyway must not be described as a phone: reading "pretending:
+    // iPhone 15 Pro" while the page cannot detect a touch screen is
+    // how a tester concludes a site is broken on mobile when it is
+    // the tool that is wrong. So the claim carries the page's answer
+    // with it, and the reader is told which part did not take.
+    for (const gap of status.gaps ?? []) {
+        lines.push(`  not landed: ${gap.what} is ${gap.observed}`);
+    }
+    if (status.throttle?.offline) {
+        lines.push("  network: offline");
+    }
+    else if (status.throttle && status.throttle.latency > 0) {
+        lines.push(`  network: throttled, ${status.throttle.latency}ms latency`);
+    }
+    if (status.recording)
+        lines.push(`  ${status.recording}`);
+    if (status.rules.length > 0) {
+        lines.push(`  intercepting: ${status.rules
+            .map((rule) => `${rule.action} ${rule.pattern}`)
+            .join(", ")}`);
+    }
+    lines.push(`  dialogs: ${status.dialogPolicy.accept ? "accepted" : "dismissed"}` +
+        `${status.dialogsSeen > 0 ? `, ${status.dialogsSeen} so far` : ""}`);
+    // A crash divides the session in two, so it is worth seeing
+    // without having to ask for the history separately.
+    const crashes = status.history.filter((event) => event.kind === "crashed").length;
+    if (crashes > 0) {
+        lines.push(`  the tab has crashed ${crashes === 1 ? "once" : `${crashes} times`}` +
+            " and been replaced");
+    }
+    const recent = status.history.slice(-RECENT_HISTORY);
+    if (recent.length > 0) {
+        lines.push("", "  recently:");
+        for (const event of recent) {
+            lines.push(`    ${event.kind}${event.url ? ` ${event.url}` : ""}`);
+        }
+    }
+    if (status.artifacts.length > 0) {
+        lines.push("", "  written to disk:");
+        for (const path of status.artifacts)
+            lines.push(`    ${path}`);
+    }
+    return lines.join("\n");
+}
+/** What the session is pretending, in one phrase. */
+function describeEmulation(state) {
+    const notes = [];
+    if (state.device)
+        notes.push(state.device);
+    else if (state.viewport) {
+        notes.push(`${state.viewport.width} by ${state.viewport.height}`);
+    }
+    if (state.colorScheme)
+        notes.push(`${state.colorScheme} mode`);
+    if (state.reducedMotion)
+        notes.push("reduced motion");
+    if (state.contrast && state.contrast !== "no-preference") {
+        notes.push(`${state.contrast} contrast`);
+    }
+    if (state.forcedColors)
+        notes.push("forced colours");
+    if (state.vision && state.vision !== "none")
+        notes.push(state.vision);
+    if (state.media === "print")
+        notes.push("print layout");
+    if (state.touch)
+        notes.push("touch");
+    if (state.timezone)
+        notes.push(state.timezone);
+    if (state.locale)
+        notes.push(state.locale);
+    if (state.cpuThrottle && state.cpuThrottle > 1) {
+        notes.push(`cpu ${state.cpuThrottle}x slower`);
+    }
+    return notes.join(", ");
+}

package/dist/web/environment/storage.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What the page has kept: local storage, session storage,
+ * cookies and the clipboard.
+ *
+ * These are where the state behind a bug usually hides. A page
+ * that behaves differently on a second visit is nearly always
+ * remembering something, and the fastest way to find out what
+ * is to look rather than to reason about it.
+ */
+/** One cookie, as the protocol describes it. */
+export interface CookieRecord {
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: number;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+    readonly sameSite?: string;
+}
+/** Everything a session can see that the page has kept. */
+export interface StorageSnapshot {
+    readonly local?: readonly (readonly [string, string])[];
+    readonly session?: readonly (readonly [string, string])[];
+    readonly cookies?: readonly CookieRecord[];
+    readonly clipboard?: string;
+    /** Why a store could not be read, when one could not. */
+    readonly unavailable?: Readonly<Record<string, string>>;
+}
+/** A signed-in state, saved so a later session can wear it. */
+export interface SavedState {
+    /** The origin these belong to. Local storage is scoped to it. */
+    readonly origin: string;
+    readonly savedAt: string;
+    readonly cookies: readonly CookieRecord[];
+    readonly local: readonly (readonly [string, string])[];
+    readonly session: readonly (readonly [string, string])[];
+}
+/** Take what a session is holding and make it keepable. */
+export declare function captureState(origin: string, snapshot: StorageSnapshot): SavedState;
+/**
+ * Read a saved state back, or say why this is not one.
+ *
+ * Checked rather than trusted, because the text comes from a path
+ * a caller typed and the failure it guards against is silent: a
+ * state that restores nothing leaves a session signed out, which
+ * looks exactly like a site that logged you out and sends someone
+ * debugging the site instead of the path. Every refusal names
+ * what was wrong so the next attempt is better informed.
+ */
+export declare function readState(text: string): SavedState | {
+    problem: string;
+};
+/** What the page is holding on to. */
+export declare function renderStorage(snapshot: StorageSnapshot): string;

package/dist/web/environment/storage.js

@@ -0,0 +1,142 @@
+/**
+ * What the page has kept: local storage, session storage,
+ * cookies and the clipboard.
+ *
+ * These are where the state behind a bug usually hides. A page
+ * that behaves differently on a second visit is nearly always
+ * remembering something, and the fastest way to find out what
+ * is to look rather than to reason about it.
+ */
+/** Take what a session is holding and make it keepable. */
+export function captureState(origin, snapshot) {
+    return {
+        origin,
+        savedAt: new Date().toISOString(),
+        cookies: snapshot.cookies ?? [],
+        local: snapshot.local ?? [],
+        session: snapshot.session ?? [],
+    };
+}
+/** Whether a value is a pair of strings, as a stored entry is. */
+function isEntry(value) {
+    return (Array.isArray(value) &&
+        value.length === 2 &&
+        value.every((part) => typeof part === "string"));
+}
+/** Whether a value carries at least what a cookie needs. */
+function isCookie(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return typeof record.name === "string" && typeof record.value === "string";
+}
+/**
+ * Read a saved state back, or say why this is not one.
+ *
+ * Checked rather than trusted, because the text comes from a path
+ * a caller typed and the failure it guards against is silent: a
+ * state that restores nothing leaves a session signed out, which
+ * looks exactly like a site that logged you out and sends someone
+ * debugging the site instead of the path. Every refusal names
+ * what was wrong so the next attempt is better informed.
+ */
+export function readState(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return { problem: `it is not JSON: ${String(err)}` };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return { problem: "it is not an object, so it holds no state" };
+    }
+    const record = parsed;
+    if (typeof record.origin !== "string" || record.origin === "") {
+        return {
+            problem: "it has no origin, so there is no way to know which site " +
+                "the local storage in it belongs to",
+        };
+    }
+    const cookies = record.cookies ?? [];
+    if (!Array.isArray(cookies) || !cookies.every(isCookie)) {
+        return {
+            problem: "its cookies are not cookies, each needing a name and a value",
+        };
+    }
+    const local = record.local ?? [];
+    const session = record.session ?? [];
+    if (!Array.isArray(local) ||
+        !local.every(isEntry) ||
+        !Array.isArray(session) ||
+        !session.every(isEntry)) {
+        return {
+            problem: "its stored entries are not name and value pairs",
+        };
+    }
+    return {
+        origin: record.origin,
+        savedAt: typeof record.savedAt === "string" ? record.savedAt : "unknown",
+        cookies,
+        local,
+        session,
+    };
+}
+/** How much of a stored value reads before it stops helping. */
+const MAX_VALUE = 200;
+/** What the page is holding on to. */
+export function renderStorage(snapshot) {
+    const sections = [];
+    for (const [label, entries] of [
+        ["local storage", snapshot.local],
+        ["session storage", snapshot.session],
+    ]) {
+        if (!entries)
+            continue;
+        sections.push(entries.length === 0
+            ? `${label}: empty`
+            : `${label}: ${entries.length} ${entries.length === 1 ? "entry" : "entries"}\n${entries
+                .map(([key, value]) => `  ${key} = ${clip(value)}`)
+                .join("\n")}`);
+    }
+    if (snapshot.cookies) {
+        sections.push(snapshot.cookies.length === 0
+            ? "cookies: none"
+            : `cookies: ${snapshot.cookies.length}\n${snapshot.cookies
+                .map((cookie) => `  ${cookie.name} = ${clip(cookie.value)}${flags(cookie)}`)
+                .join("\n")}`);
+    }
+    if (snapshot.clipboard !== undefined) {
+        sections.push(snapshot.clipboard === ""
+            ? "clipboard: empty"
+            : `clipboard: ${clip(snapshot.clipboard)}`);
+    }
+    for (const [store, why] of Object.entries(snapshot.unavailable ?? {})) {
+        sections.push(`${store}: could not be read. ${why}`);
+    }
+    return sections.length === 0
+        ? "Nothing was asked for."
+        : sections.join("\n\n");
+}
+/** The properties that change what a cookie is for. */
+function flags(cookie) {
+    const noted = [];
+    if (cookie.httpOnly)
+        noted.push("httpOnly");
+    if (cookie.secure)
+        noted.push("secure");
+    if (cookie.sameSite)
+        noted.push(`sameSite=${cookie.sameSite}`);
+    // A session cookie has no expiry, which the protocol reports
+    // as -1 rather than as an absent field.
+    if (cookie.expires !== undefined && cookie.expires < 0) {
+        noted.push("session");
+    }
+    return noted.length === 0 ? "" : `  [${noted.join(", ")}]`;
+}
+/** A value cut to length, with the cut declared. */
+function clip(value) {
+    return value.length > MAX_VALUE
+        ? `${value.slice(0, MAX_VALUE)}... (${value.length} chars)`
+        : value;
+}

package/dist/web/environment/tabs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The tabs a session can see.
+ *
+ * A session drives one tab at a time, which is almost always what
+ * is wanted and is wrong exactly when a page opens another one: a
+ * target of _blank, a window.open, a payment or sign-in handed to
+ * a second window. What the page did then is real and invisible,
+ * and the last thing a caller sees is a click that appeared to do
+ * nothing.
+ */
+/** One tab the session's browser context is holding open. */
+export interface TabRecord {
+    /** Its place in the list, from one, as a caller names it. */
+    readonly index: number;
+    readonly url: string;
+    readonly title: string;
+    /** Whether this is the one every read and act goes to. */
+    readonly current: boolean;
+}
+/** The tabs open, and which one is being driven. */
+export declare function renderTabs(tabs: readonly TabRecord[]): string;
+/**
+ * Pick the tab asked for, or refuse by saying what is open.
+ *
+ * The refusal carries the list because the caller's next move is
+ * always to ask for it, and making them spend a call to learn
+ * what was already in hand when the refusal was written is a
+ * needless round trip.
+ */
+export declare function chooseTab(tabs: readonly TabRecord[], wanted: number): TabRecord | {
+    refusal: string;
+};

package/dist/web/environment/tabs.js

@@ -0,0 +1,47 @@
+/**
+ * The tabs a session can see.
+ *
+ * A session drives one tab at a time, which is almost always what
+ * is wanted and is wrong exactly when a page opens another one: a
+ * target of _blank, a window.open, a payment or sign-in handed to
+ * a second window. What the page did then is real and invisible,
+ * and the last thing a caller sees is a click that appeared to do
+ * nothing.
+ */
+/** The tabs open, and which one is being driven. */
+export function renderTabs(tabs) {
+    if (tabs.length === 0)
+        return "No tabs open.";
+    if (tabs.length === 1) {
+        const only = tabs[0];
+        return `One tab: ${describe(only)}`;
+    }
+    const lines = tabs.map((tab) => `${tab.index}. ${describe(tab)}${tab.current ? "  <- driving" : ""}`);
+    return [`${tabs.length} tabs open:`, ...lines].join("\n");
+}
+/** A tab in one line, title first because that is what is read. */
+function describe(tab) {
+    return tab.title === "" ? tab.url : `${tab.title} (${tab.url})`;
+}
+/**
+ * Pick the tab asked for, or refuse by saying what is open.
+ *
+ * The refusal carries the list because the caller's next move is
+ * always to ask for it, and making them spend a call to learn
+ * what was already in hand when the refusal was written is a
+ * needless round trip.
+ */
+export function chooseTab(tabs, wanted) {
+    const found = tabs.find((tab) => tab.index === wanted);
+    if (found !== undefined)
+        return found;
+    if (tabs.length === 0) {
+        return {
+            refusal: "There are no tabs open to switch to, which means the session " +
+                "has no page at all rather than the wrong one.",
+        };
+    }
+    return {
+        refusal: `There is no tab ${wanted}. Open are:\n${renderTabs(tabs)}`,
+    };
+}

package/dist/web/environment/view.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reading the emulated environment back.
+ *
+ * Led by what the page observes rather than by what was asked
+ * for, so a setting that did not take cannot read as though it
+ * did.
+ */
+import type { Divergence, EmulationState, ObservedEnvironment } from "./emulation.js";
+/** What the page is experiencing, and where that differs from the ask. */
+export declare function renderEnvironment(asked: EmulationState, observed: ObservedEnvironment, gaps: readonly Divergence[]): string;