@browserstack/mcp-server 2.2.6-beta.1 → 2.2.6-beta.2

package/dist/tools/accessiblity-utils/paginate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How a report's issues are handed out: most severe first, in pages measured by the length
+ * of their JSON, so that a page fits a client's context whatever the rows contain. The
+ * cursor an agent passes back is the character offset the next page starts at.
+ */
+/** Most severe first; an unknown severity sorts last. */
+export declare function sortBySeverity<T extends {
+    severity: string;
+}>(rows: T[]): T[];
+/**
+ * How many characters of issue JSON one call hands out by default: about 2,500 tokens, so
+ * a page stays small next to a client's own limit on tool output while a large report
+ * still takes few calls.
+ */
+export declare const PAGE_CHARACTERS = 10000;
+export interface Page<T> {
+    records: T[];
+    page_length: number;
+    /** Character offset of the next page, or null when this was the last. */
+    next_page: number | null;
+    /** How many rows the pages after this one hold. */
+    remaining: number;
+}
+export declare function pageOf<T>(all: T[], { maxCharacterLength, nextPage }?: {
+    maxCharacterLength?: number | undefined;
+    nextPage?: number | undefined;
+}): Page<T>;

package/dist/tools/accessiblity-utils/paginate.js

@@ -0,0 +1,50 @@
+/**
+ * How a report's issues are handed out: most severe first, in pages measured by the length
+ * of their JSON, so that a page fits a client's context whatever the rows contain. The
+ * cursor an agent passes back is the character offset the next page starts at.
+ */
+const SEVERITY_ORDER = {
+    critical: 0,
+    serious: 1,
+    moderate: 2,
+    minor: 3,
+};
+/** Most severe first; an unknown severity sorts last. */
+export function sortBySeverity(rows) {
+    return rows.sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 99) - (SEVERITY_ORDER[b.severity] ?? 99));
+}
+/**
+ * How many characters of issue JSON one call hands out by default: about 2,500 tokens, so
+ * a page stays small next to a client's own limit on tool output while a large report
+ * still takes few calls.
+ */
+export const PAGE_CHARACTERS = 10_000;
+export function pageOf(all, { maxCharacterLength = PAGE_CHARACTERS, nextPage = 0 } = {}) {
+    // Walk to the starting offset
+    let charCursor = 0;
+    let idx = 0;
+    for (; idx < all.length; idx++) {
+        const len = JSON.stringify(all[idx]).length;
+        if (charCursor + len > nextPage)
+            break;
+        charCursor += len;
+    }
+    // Collect up to maxCharacterLength; a row larger than that still makes a page of its
+    // own, or the cursor would never move past it
+    const page = [];
+    for (let i = idx; i < all.length; i++) {
+        const recStr = JSON.stringify(all[i]);
+        const fits = charCursor - nextPage + recStr.length <= maxCharacterLength;
+        if (!fits && page.length > 0)
+            break;
+        page.push(all[i]);
+        charCursor += recStr.length;
+    }
+    const remaining = all.length - idx - page.length;
+    return {
+        records: page,
+        page_length: page.length,
+        next_page: remaining > 0 ? charCursor : null,
+        remaining,
+    };
+}

package/dist/tools/accessiblity-utils/report-fetcher.d.ts

@@ -1,4 +1,9 @@
-/** What to read issues from: a Website Scanner run, an Automated Tests build or a Workflow Analyzer report. */
+import { type AppBuildIssues, type AppBuildRef, type AppBuildReport, type AppBuildRow, type AppManualReport, type AppManualReportRow, type AppProjectRow } from "./app-report-fetcher.js";
+export { MAX_APP_BUILD_LIST_PAGES } from "./app-report-fetcher.js";
+/**
+ * What to read issues from: a Website Scanner run, an Automated Tests build, a Workflow
+ * Analyzer report, or an App Accessibility build (a mobile app run through App Automate).
+ */
 export type IssueSource = {
     kind: "scan";
     scanId: string;
@@ -9,6 +14,12 @@ export type IssueSource = {
 } | {
     kind: "workflow";
     reportId: string;
+} | {
+    kind: "appBuild";
+    buildId: string;
+} | {
+    kind: "appReport";
+    reportId: string;
 };
 /**
  * How far a report link's scan is searched for. The scan list has no name or link filter and
@@ -17,8 +28,46 @@ export type IssueSource = {
  * at limit=50 or 100 the cursor skips scans, so a larger page cannot be used to go faster.
  */
 export declare const MAX_SCAN_LIST_PAGES = 15;
+/**
+ * How long one call waits on a CSV export. Export time grows with the report's rows: a few
+ * seconds for hundreds, ~17 s for 18k rows, over 2 minutes for 30k issues. A call stays well
+ * under the 60 s request timeout MCP clients default to; an export still running after this
+ * is handed back to be continued by the next call rather than started again.
+ */
+export declare const EXPORT_WAIT_MS = 45000;
+/**
+ * Exports per report, kept for the life of the server: the finished link to reuse for later
+ * pages, or the task of an export still running, to continue instead of starting another.
+ * Keyed by the account and the report, so one account never sees another's.
+ */
+export declare const reportExports: Map<string, {
+    link?: string;
+    expiresAt?: number;
+    taskId?: string;
+}>;
+/** An export still being generated when a call stopped waiting on it. */
+export declare class ExportPendingError extends Error {
+    readonly taskId: string;
+    readonly waitedMs: number;
+    constructor(taskId: string, waitedMs: number);
+}
+/** A run in a scan's history, newest first in the API's list. */
+export interface ScanRun {
+    id: number;
+    scanDate: string;
+    issues?: number;
+}
+/** What the dashboard counts between a run and the run before it. */
+export interface RunChanges {
+    newIssues: number;
+    retainedIssues: number;
+    resolvedIssues: number;
+}
 export declare class AccessibilityReportFetcher {
     private auth;
+    private readonly app;
+    /** Web builds whose overview was read, by id, so a status check need not read it again. */
+    private readonly webBuildProjects;
     setAuth(auth: {
         username: string;
         password: string;
@@ -26,18 +75,78 @@ export declare class AccessibilityReportFetcher {
     private authHeaders;
     /**
      * The source a dashboard report link points at. An Automated Tests link carries the build
-     * id itself. A Website Scanner link carries the thBuildId of one run, which only the scan
-     * list can map to ids: each scan there carries its latest run's link. A link to an older
-     * run therefore matches no scan, and is reported as such rather than guessed at.
+     * id itself. An Automate build or session link is mapped to that build through a session
+     * (see buildOfAutomateSession). A Website Scanner link carries the thBuildId of one run,
+     * which only the scan list can map to ids: each scan there carries its latest run's link.
+     * A link to an older run therefore matches no scan, and is reported as such rather than
+     * guessed at. A scanner share link carries the dashboard link it shows. An App
+     * Accessibility link names its build by project, name and number, which the project's
+     * build list maps to the id. An App Automate build or session link maps to the
+     * accessibility build through a session's test code.
      */
     sourceFromReportUrl(reportUrl: string): Promise<IssueSource>;
+    /**
+     * A build id names a web build or a mobile app build: both are TestHub ids, and only the
+     * API that ran the build knows it. The web API is asked first; a build it does not know
+     * that the App Accessibility API does is an app build. One neither knows is refused
+     * here, naming both.
+     */
+    resolveBuild(source: IssueSource): Promise<IssueSource>;
+    /** An app build's issues, read inline from its scanned screens. */
+    appBuildReport(buildId: string, cursor?: number, maxCharacterLength?: number): Promise<AppBuildReport>;
+    /** Every issue of an app build at once, to compare it with another. */
+    appBuildIssues(buildId: string): Promise<AppBuildIssues>;
+    /** The build before an app build in its project, if it has one. */
+    previousAppBuild(buildId: string): Promise<AppBuildRef | undefined>;
+    /** A manual (Workflow Analyzer) app report's issues, read inline from its screens. */
+    appReportIssues(reportId: string, cursor?: number, maxCharacterLength?: number): Promise<AppManualReport>;
+    listAppProjects(limit: number): Promise<{
+        projects: AppProjectRow[];
+        total: number;
+    }>;
+    listAppBuilds(projectName: string, buildName: string | undefined, limit: number): Promise<{
+        project: {
+            id: number;
+            name: string;
+        };
+        total: number;
+        builds: AppBuildRow[];
+    }>;
+    listAppManualReports(name: string | undefined, limit: number): Promise<{
+        total: number;
+        reports: AppManualReportRow[];
+    }>;
+    /** Any one session of an Automate build; every session of an SDK run names the same build. */
+    private anyAutomateSession;
+    /**
+     * The Accessibility build an Automate session ran in. A session run through the BrowserStack
+     * SDK belongs to the SDK's build, whose id is also the Accessibility build id, and the
+     * session's test-code record names it (build_uuid). A session run without the SDK has no
+     * such record, and an SDK run without accessibility testing has a build the Accessibility
+     * API does not know; both are said plainly instead of surfacing later as a bare 404.
+     */
+    private buildOfAutomateSession;
     /** Walk the newest scans for the one whose own link carries this thBuildId. */
     private findScanRun;
-    getReportLink(source: IssueSource): Promise<string>;
+    /**
+     * The CSV link of a report's issues. A finished export is reused until its link expires.
+     * Otherwise an export is started, or continued (`exportTaskId`, or the one an earlier call
+     * left running), and waited on for up to EXPORT_WAIT_MS; one still running then is handed
+     * back as an ExportPendingError carrying its task id.
+     */
+    getReportLink(source: IssueSource, options?: {
+        exportTaskId?: string;
+        onWait?: (waitedMs: number) => Promise<void>;
+    }): Promise<string>;
+    /** The run before `scanRunId` in its scan's history, or undefined for the first run. */
+    previousScanRun(scanId: string, scanRunId: string): Promise<ScanRun | undefined>;
+    /** The dashboard's new / retained / resolved counts against the run before this one. */
+    changesSinceLastRun(scanId: string, scanRunId: string): Promise<RunChanges | undefined>;
     /**
      * Where the report is in its processing, as the report's own status reads it: `completed`,
-     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added.
-     * Undefined when it cannot be read. A build's overview carries no status, so a build's comes
+     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added
+     * (an app build reads `running` / `rule_processing` until its rules have run). Undefined
+     * when it cannot be read. A web build's overview carries no status, so a build's comes
      * from its project's build list (newest first), found by id.
      */
     reportStatus(source: IssueSource): Promise<string | undefined>;

package/dist/tools/accessiblity-utils/report-fetcher.js

@@ -1,4 +1,9 @@
 import { apiClient } from "../../lib/apiClient.js";
+import { AppAccessibilityApi, manualReportIdFromDashboardLink, manualReportStatus, } from "./app-report-fetcher.js";
+export { MAX_APP_BUILD_LIST_PAGES } from "./app-report-fetcher.js";
+import { SessionType } from "../../lib/constants.js";
+import { sessionsListUrl } from "../automate-utils/list-session-ids.js";
+import { getAutomationBaseUrl } from "../rca-agent-utils/constants.js";
 const API_BASE = "https://api-accessibility.browserstack.com/api";
 /**
  * How far a report link's scan is searched for. The scan list has no name or link filter and
@@ -7,8 +12,50 @@ const API_BASE = "https://api-accessibility.browserstack.com/api";
  * at limit=50 or 100 the cursor skips scans, so a larger page cannot be used to go faster.
  */
 export const MAX_SCAN_LIST_PAGES = 15;
+/** How many pages of a scan's runs are read to find the run before a given one. */
+const MAX_SCAN_RUN_PAGES = 10;
 /** A build whose status is checked is one just run, so it sits at the top of its project's list. */
 const MAX_BUILD_LIST_PAGES = 3;
+/**
+ * How long one call waits on a CSV export. Export time grows with the report's rows: a few
+ * seconds for hundreds, ~17 s for 18k rows, over 2 minutes for 30k issues. A call stays well
+ * under the 60 s request timeout MCP clients default to; an export still running after this
+ * is handed back to be continued by the next call rather than started again.
+ */
+export const EXPORT_WAIT_MS = 45_000;
+const EXPORT_POLL_MS = [1000, 2000, 3000, 5000];
+/** A finished export's link is reused until shortly before it expires (about 12 hours). */
+const LINK_EXPIRY_MARGIN_MS = 10 * 60 * 1000;
+const LINK_FALLBACK_TTL_MS = 60 * 60 * 1000;
+/**
+ * Exports per report, kept for the life of the server: the finished link to reuse for later
+ * pages, or the task of an export still running, to continue instead of starting another.
+ * Keyed by the account and the report, so one account never sees another's.
+ */
+export const reportExports = new Map();
+/** An export still being generated when a call stopped waiting on it. */
+export class ExportPendingError extends Error {
+    taskId;
+    waitedMs;
+    constructor(taskId, waitedMs) {
+        super(`The report's CSV export is still being generated after ${Math.round(waitedMs / 1000)}s (export task ${taskId}).`);
+        this.taskId = taskId;
+        this.waitedMs = waitedMs;
+        this.name = "ExportPendingError";
+    }
+}
+/** When a presigned export link stops working, from its Expires parameter. */
+function linkExpiry(link) {
+    try {
+        const expires = Number(new URL(link).searchParams.get("Expires"));
+        if (expires > 0)
+            return expires * 1000 - LINK_EXPIRY_MARGIN_MS;
+    }
+    catch {
+        // Not a URL we can read; fall back below.
+    }
+    return Date.now() + LINK_FALLBACK_TTL_MS;
+}
 /** The thBuildId a dashboard report link carries, if any. */
 function thBuildIdOf(link) {
     try {
@@ -47,6 +94,9 @@ function exportUrls(source) {
                 poll: (taskId) => `${route}?taskId=${q(taskId)}`,
             };
         }
+        case "appBuild":
+        case "appReport":
+            throw new Error("An App Accessibility build or report has no CSV export; its issues are read inline");
     }
 }
 /** Why an export did not start, in the API's words, and where a build's id comes from when it is not found. */
@@ -56,12 +106,24 @@ function startFailure(source, status, body) {
         `HTTP ${status}`;
     // The API takes only its own build id; the Automate build id is a 404 "Build not found".
     const hint = status === 404 && source.kind === "build"
-        ? ". Pass the Accessibility build id: the thBuildId in the build's accessibility report link (40 lowercase letters and digits), not the Automate build id or the build name"
+        ? ". Pass the Accessibility build id: the thBuildId in the build's accessibility report link (40 lowercase letters and digits), not the Automate build id or the build name. For an Automate build or session, pass its Automate dashboard link as reportUrl"
         : "";
     return `Failed to initiate report: ${reason}${hint}`;
 }
+/** The build and session ids an Automate dashboard link carries, if it is one. */
+function automateIds(url) {
+    if (url.hostname !== "automate.browserstack.com")
+        return undefined;
+    return {
+        buildId: url.pathname.match(/\/builds\/([0-9a-f]{40})(?:\/|$)/i)?.[1],
+        sessionId: url.pathname.match(/\/sessions\/([0-9a-f]{40})(?:\/|$)/i)?.[1],
+    };
+}
 export class AccessibilityReportFetcher {
     auth;
+    app = new AppAccessibilityApi(() => this.authHeaders());
+    /** Web builds whose overview was read, by id, so a status check need not read it again. */
+    webBuildProjects = new Map();
     setAuth(auth) {
         this.auth = auth;
     }
@@ -75,9 +137,14 @@ export class AccessibilityReportFetcher {
     }
     /**
      * The source a dashboard report link points at. An Automated Tests link carries the build
-     * id itself. A Website Scanner link carries the thBuildId of one run, which only the scan
-     * list can map to ids: each scan there carries its latest run's link. A link to an older
-     * run therefore matches no scan, and is reported as such rather than guessed at.
+     * id itself. An Automate build or session link is mapped to that build through a session
+     * (see buildOfAutomateSession). A Website Scanner link carries the thBuildId of one run,
+     * which only the scan list can map to ids: each scan there carries its latest run's link.
+     * A link to an older run therefore matches no scan, and is reported as such rather than
+     * guessed at. A scanner share link carries the dashboard link it shows. An App
+     * Accessibility link names its build by project, name and number, which the project's
+     * build list maps to the id. An App Automate build or session link maps to the
+     * accessibility build through a session's test code.
      */
     async sourceFromReportUrl(reportUrl) {
         let url;
@@ -87,6 +154,26 @@ export class AccessibilityReportFetcher {
         catch {
             url = undefined;
         }
+        // A scanner share link (scanner.browserstack.com/.../a11y-report) carries the dashboard
+        // link it shows as its reportUrl parameter.
+        const shared = url?.searchParams.get("reportUrl");
+        if (shared && shared !== reportUrl)
+            return this.sourceFromReportUrl(shared);
+        const manualReportId = url && manualReportIdFromDashboardLink(url);
+        if (manualReportId)
+            return { kind: "appReport", reportId: manualReportId };
+        const appBuildId = url &&
+            ((await this.app.buildIdFromDashboardLink(url)) ??
+                (await this.app.buildIdFromAppAutomateLink(url)));
+        if (appBuildId)
+            return { kind: "appBuild", buildId: appBuildId };
+        const automate = url && automateIds(url);
+        if (automate?.sessionId) {
+            return this.buildOfAutomateSession(automate.sessionId);
+        }
+        if (automate?.buildId) {
+            return this.buildOfAutomateSession(await this.anyAutomateSession(automate.buildId));
+        }
         const thBuildId = url?.searchParams.get("thBuildId");
         if (url && thBuildId && url.pathname.includes("/automated-tests/")) {
             return { kind: "build", buildId: thBuildId };
@@ -95,7 +182,107 @@ export class AccessibilityReportFetcher {
         if (thBuildId && scanName) {
             return this.findScanRun(thBuildId, decodeURIComponent(scanName));
         }
-        throw new Error("This link does not name a report the API can look up. Pass an Automated Tests or Website Scanner report link from the Accessibility dashboard (both carry thBuildId), or the ids: scanId with scanRunId, buildId, or workflowReportId");
+        throw new Error("This link does not name a report the API can look up. Pass an Automated Tests or Website Scanner report link from the Accessibility dashboard (both carry thBuildId) or a scanner share link, an Automate build or session link, an App Accessibility build link (automated-tests/projects/…/builds/…), an App Automate build or session link, an App Accessibility manual report link (report/…), or the ids: scanId with scanRunId, buildId, workflowReportId, or appReportId");
+    }
+    /**
+     * A build id names a web build or a mobile app build: both are TestHub ids, and only the
+     * API that ran the build knows it. The web API is asked first; a build it does not know
+     * that the App Accessibility API does is an app build. One neither knows is refused
+     * here, naming both.
+     */
+    async resolveBuild(source) {
+        if (source.kind !== "build")
+            return source;
+        const web = await this.getData(`${API_BASE}/automated-tests/v1/builds/${encodeURIComponent(source.buildId)}`);
+        if (web) {
+            if (web.projectName) {
+                this.webBuildProjects.set(source.buildId, web.projectName);
+            }
+            return source;
+        }
+        const meta = await this.app.buildMeta(source.buildId);
+        if (meta)
+            return { kind: "appBuild", buildId: source.buildId };
+        throw new Error(`No Automated Tests (web) or App Accessibility build with id "${source.buildId}". Pass the id the BrowserStack SDK printed as "testhub id" at the end of the run (40 lowercase letters and digits), or the report's dashboard link as reportUrl`);
+    }
+    /** An app build's issues, read inline from its scanned screens. */
+    appBuildReport(buildId, cursor = 0, maxCharacterLength) {
+        return this.app.report(buildId, cursor, maxCharacterLength);
+    }
+    /** Every issue of an app build at once, to compare it with another. */
+    appBuildIssues(buildId) {
+        return this.app.buildIssues(buildId);
+    }
+    /** The build before an app build in its project, if it has one. */
+    previousAppBuild(buildId) {
+        return this.app.previousBuild(buildId);
+    }
+    /** A manual (Workflow Analyzer) app report's issues, read inline from its screens. */
+    appReportIssues(reportId, cursor = 0, maxCharacterLength) {
+        return this.app.appReportIssues(reportId, cursor, maxCharacterLength);
+    }
+    listAppProjects(limit) {
+        return this.app.listAppProjects(limit);
+    }
+    listAppBuilds(projectName, buildName, limit) {
+        return this.app.listAppBuilds(projectName, buildName, limit);
+    }
+    listAppManualReports(name, limit) {
+        return this.app.listAppManualReports(name, limit);
+    }
+    /** Any one session of an Automate build; every session of an SDK run names the same build. */
+    async anyAutomateSession(automateBuildId) {
+        const resp = await apiClient.get({
+            url: `${sessionsListUrl(SessionType.Automate, automateBuildId)}?limit=1`,
+            headers: this.authHeaders(),
+            raise_error: false,
+        });
+        if (resp.status === 404) {
+            throw new Error(`No Automate build with id ${automateBuildId}`);
+        }
+        if (!resp.ok) {
+            throw new Error(`Could not list the sessions of Automate build ${automateBuildId}: HTTP ${resp.status}`);
+        }
+        const sessionId = resp.data?.[0]?.automation_session?.hashed_id;
+        if (!sessionId) {
+            throw new Error(`Automate build ${automateBuildId} has no sessions`);
+        }
+        return sessionId;
+    }
+    /**
+     * The Accessibility build an Automate session ran in. A session run through the BrowserStack
+     * SDK belongs to the SDK's build, whose id is also the Accessibility build id, and the
+     * session's test-code record names it (build_uuid). A session run without the SDK has no
+     * such record, and an SDK run without accessibility testing has a build the Accessibility
+     * API does not know; both are said plainly instead of surfacing later as a bare 404.
+     */
+    async buildOfAutomateSession(sessionId) {
+        const resp = await apiClient.get({
+            url: `${getAutomationBaseUrl()}/ext/v1/sessions/${encodeURIComponent(sessionId)}/testCode`,
+            headers: this.authHeaders(),
+            raise_error: false,
+        });
+        if (!resp.ok && resp.status !== 404) {
+            throw new Error(`Could not read Automate session ${sessionId}: HTTP ${resp.status}`);
+        }
+        const buildId = resp.ok
+            ? resp.data?.build_uuid
+            : undefined;
+        if (!buildId) {
+            throw new Error(`Automate session ${sessionId} is not linked to a BrowserStack SDK build (it was not run through the SDK, or belongs to another account), so it has no accessibility results`);
+        }
+        const build = await apiClient.get({
+            url: `${API_BASE}/automated-tests/v1/builds/${encodeURIComponent(buildId)}`,
+            headers: this.authHeaders(),
+            raise_error: false,
+        });
+        if (build.status === 404) {
+            throw new Error(`This Automate run belongs to build ${buildId}, which has no accessibility results: accessibility testing was not on for it`);
+        }
+        if (!build.ok) {
+            throw new Error(`Could not read accessibility build ${buildId} of this Automate run: HTTP ${build.status}`);
+        }
+        return { kind: "build", buildId };
     }
     /** Walk the newest scans for the one whose own link carries this thBuildId. */
     async findScanRun(thBuildId, scanName) {
@@ -130,7 +317,7 @@ export class AccessibilityReportFetcher {
             nextPage = data.pagination.nextPage;
         }
         if (sameName !== undefined) {
-            throw new Error(`This link is to an earlier run of scan "${scanName}" (scanId ${sameName}). A link resolves only to a scan's latest run; ask the user for that run's scanRunId and pass it with scanId ${sameName}`);
+            throw new Error(`This link is to an earlier run of scan "${scanName}" (scanId ${sameName}). A link resolves only to a scan's latest run; ask the user for that run's scanRunId and pass it with scanId ${sameName}, or read the latest run with compareWith: "previous" to compare it with the run before it`);
         }
         // nextPage is still set only when the walk stopped at the page cap, not at the end.
         const searched = nextPage
@@ -138,44 +325,89 @@ export class AccessibilityReportFetcher {
             : "";
         throw new Error(`No Website Scanner scan${searched} matches this link. Pass scanId and scanRunId instead`);
     }
-    async getReportLink(source) {
+    /**
+     * The CSV link of a report's issues. A finished export is reused until its link expires.
+     * Otherwise an export is started, or continued (`exportTaskId`, or the one an earlier call
+     * left running), and waited on for up to EXPORT_WAIT_MS; one still running then is handed
+     * back as an ExportPendingError carrying its task id.
+     */
+    async getReportLink(source, options = {}) {
+        const key = `${this.auth?.username ?? ""}|${JSON.stringify(source)}`;
+        const known = reportExports.get(key);
+        if (known?.link && (known.expiresAt ?? 0) > Date.now())
+            return known.link;
         const urls = exportUrls(source);
-        // Initiate CSV link generation
-        const initResp = await apiClient.get({
-            url: urls.start,
-            headers: this.authHeaders(),
-            raise_error: false,
-        });
-        const initData = initResp.data;
-        if (!initResp.ok || !initData?.success) {
-            throw new Error(startFailure(source, initResp.status, initData));
-        }
-        const taskId = initData.data.task_id;
-        // Poll for the generated CSV link (task is async, may take a few seconds)
-        const reportUrl = urls.poll(taskId);
-        const maxAttempts = 3;
-        const pollIntervalMs = 2000;
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let taskId = options.exportTaskId ?? known?.taskId;
+        if (!taskId) {
+            const initResp = await apiClient.get({
+                url: urls.start,
+                headers: this.authHeaders(),
+                raise_error: false,
+            });
+            const initData = initResp.data;
+            if (!initResp.ok || !initData?.success) {
+                throw new Error(startFailure(source, initResp.status, initData));
+            }
+            taskId = initData.data.task_id;
+        }
+        reportExports.set(key, { taskId });
+        const started = Date.now();
+        for (let attempt = 0;; attempt++) {
             const reportResp = await apiClient.get({
-                url: reportUrl,
+                url: urls.poll(taskId),
                 headers: this.authHeaders(),
             });
             const reportData = reportResp.data;
             if (!reportData.success) {
+                reportExports.delete(key);
                 throw new Error(`Failed to fetch report: ${reportData.error}`);
             }
             const link = reportData.data?.reportLink;
             if (link) {
+                reportExports.set(key, { link, expiresAt: linkExpiry(link) });
                 return link;
             }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            const message = reportData.data?.message ?? "";
+            if (/generation failed/i.test(message)) {
+                reportExports.delete(key);
+                throw new Error(`The report's CSV export failed: ${message}`);
+            }
+            const waited = Date.now() - started;
+            if (waited >= EXPORT_WAIT_MS)
+                throw new ExportPendingError(taskId, waited);
+            await options.onWait?.(waited);
+            const pause = EXPORT_POLL_MS[Math.min(attempt, EXPORT_POLL_MS.length - 1)];
+            await new Promise((resolve) => setTimeout(resolve, pause));
         }
-        throw new Error(`Report link was not available after ${maxAttempts} attempts. The CSV generation may still be in progress.`);
+    }
+    /** The run before `scanRunId` in its scan's history, or undefined for the first run. */
+    async previousScanRun(scanId, scanRunId) {
+        // The runs come a page at a time; the one before may be on a later page.
+        const runs = [];
+        const base = `${API_BASE}/website-scanner/v1/scans/${encodeURIComponent(scanId)}/scan_runs`;
+        let nextPage;
+        for (let page = 0; page < MAX_SCAN_RUN_PAGES; page++) {
+            const data = await this.getData(nextPage ? `${base}?nextPage=${encodeURIComponent(nextPage)}` : base);
+            runs.push(...(data?.scanRuns ?? []));
+            if (!data?.pagination?.hasNext || !data.pagination.nextPage)
+                break;
+            nextPage = data.pagination.nextPage;
+        }
+        const newestFirst = [...runs].sort((a, b) => b.scanDate.localeCompare(a.scanDate));
+        const at = newestFirst.findIndex((run) => String(run.id) === scanRunId);
+        return at >= 0 ? newestFirst[at + 1] : undefined;
+    }
+    /** The dashboard's new / retained / resolved counts against the run before this one. */
+    async changesSinceLastRun(scanId, scanRunId) {
+        const q = encodeURIComponent;
+        const changes = (await this.getData(`${API_BASE}/website-scanner/v1/scans/${q(scanId)}/scan_runs/${q(scanRunId)}`))?.changesSinceLastRun;
+        return changes ?? undefined;
     }
     /**
      * Where the report is in its processing, as the report's own status reads it: `completed`,
-     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added.
-     * Undefined when it cannot be read. A build's overview carries no status, so a build's comes
+     * or `queued` / `running` / `processing` / `finalizing` while issues are still being added
+     * (an app build reads `running` / `rule_processing` until its rules have run). Undefined
+     * when it cannot be read. A web build's overview carries no status, so a build's comes
      * from its project's build list (newest first), found by id.
      */
     async reportStatus(source) {
@@ -188,6 +420,12 @@ export class AccessibilityReportFetcher {
                     return (await this.getData(`${API_BASE}/workflow-analyzer/v1/reports/${q(source.reportId)}`))?.summary?.status;
                 case "build":
                     return await this.buildStatus(source.buildId);
+                case "appBuild":
+                    return (await this.app.buildMeta(source.buildId))?.status;
+                case "appReport": {
+                    const detail = await this.app.manualReport(source.reportId);
+                    return detail ? manualReportStatus(detail) : undefined;
+                }
             }
         }
         catch {
@@ -196,7 +434,8 @@ export class AccessibilityReportFetcher {
     }
     async buildStatus(buildId) {
         const q = encodeURIComponent;
-        const project = (await this.getData(`${API_BASE}/automated-tests/v1/builds/${q(buildId)}`))?.projectName;
+        const project = this.webBuildProjects.get(buildId) ??
+            (await this.getData(`${API_BASE}/automated-tests/v1/builds/${q(buildId)}`))?.projectName;
         if (!project)
             return undefined;
         let nextPage;