import { type BrowserContext, type Page } from "playwright-core";
/** One top-level element of the authored slide, measured against the viewport
 * for the print-safe-zone check. Viewport-relative CSS px. */
export interface SafeZoneItem {
  label: string;
  left: number;
  top: number;
  right: number;
  bottom: number;
  width: number;
  height: number;
}
/**
 * The safe-zone verdict for one measured element: a message naming every page
 * edge the element gets closer to than `safeMargin`, or null when it stays
 * clear. A distance exactly at the margin passes — the margin is a floor.
 */
export declare function safeZoneFailureMessage(
  item: SafeZoneItem,
  viewportWidth: number,
  viewportHeight: number,
  safeMargin: number,
): string | null;
/** One check failure. Deck-level failures (browser errors, frame-count
 * mismatches) carry only `message`; per-slide failures name the 1-based deck
 * position and, when zerp could attribute it, the source file to edit. */
export interface VerifyFailure {
  slide?: number;
  src?: string;
  message: string;
}
/** The human line for a failure: `slide N (slides/foo.html): message`. */
export declare function formatVerifyFailure(failure: VerifyFailure): string;
/**
 * Budget for one browser session when the caller names none.
 *
 * It covers everything: launching a cold browser, navigating, waiting for the
 * inlined fonts to activate, and running the probe. Fine for a laptop with a
 * warm page cache, and deliberately overridable — the same work on a small,
 * loaded CI or container host, or on a deck carrying megabytes of imagery, can
 * take several times as long, and a session that runs out of budget yields no
 * report at all rather than a slow one.
 */
export declare const DEFAULT_VERIFICATION_TIMEOUT_MS = 20000;
/**
 * The session budget in ms: an explicit option, else the environment, else the
 * default.
 *
 * A malformed env value throws rather than falling back. Silently ignoring it
 * would leave the operator who set it believing verification has a budget it
 * does not have — the failure that raising the timeout was meant to prevent,
 * now invisible.
 */
export declare function resolveVerificationTimeoutMs(explicit?: number): number;
/**
 * The already-running browser to verify in: an explicit option, else the
 * environment, else none (launch one).
 *
 * Rejects an endpoint whose scheme names no transport rather than guessing, for
 * the same reason a malformed timeout throws — a host that configured browser
 * reuse and silently got a per-run launch has the cost it was trying to avoid
 * and no signal that it does.
 */
export declare function resolveBrowserEndpoint(explicit?: string): string | undefined;
/**
 * Resolve a Chromium executable for headless work, in priority order:
 *
 *   1. `CHROME_BIN` — an explicit override (wrapper scripts that exec a
 *      browser with extra flags are supported), validated the same way the
 *      system candidates in step 3 are: a path-like value must exist, and
 *      the binary must actually run `--version`. An unvalidated override
 *      would otherwise surface as a raw Playwright launch failure three
 *      layers away from the typo that caused it, instead of a clear,
 *      actionable error naming the bad path right here.
 *   2. playwright-core's own managed chromium, if `zerp install-browser` (or a
 *      prior playwright install) has downloaded it. `executablePath()` computes
 *      a path whether or not it exists — and throws in some builds when nothing
 *      is installed — so guard it with `existsSync`.
 *   3. A system-installed Chrome/Chromium, validated by `--version`.
 *   4. None found — point at `zerp install-browser` or `CHROME_BIN`.
 *
 * Exported so every headless entry point resolves a browser identically — the
 * docs PDF build (`scripts/build-docs.mjs`) and the check probe both use it.
 */
export declare function resolveBrowserExecutable(): string;
export interface BrowserSessionOptions {
  /** Absent when {@link BrowserSessionOptions.browserEndpoint} supplies a browser instead. */
  executablePath?: string;
  htmlPath: string;
  width: number;
  height: number;
  timeoutMs: number;
  /** An already-running browser to use, instead of launching one:
   * `http(s)://` connects over CDP, `ws(s)://` over the playwright protocol.
   * The browser belongs to whoever started it and is never closed here. */
  browserEndpoint?: string;
  /** Named by the caller so a timeout names the budget that ran out and the
   * flag/env var that raises it — the one failure whose fix is a
   * configuration change the operator cannot make without knowing which
   * value was too small. */
  timeoutMessage: string;
}
/**
 * Drive Chromium through playwright-core (a battle-tested browser driver with
 * no bundled browsers of its own) for one session: borrow or launch a
 * browser, open an exact-viewport context, install the error collector,
 * navigate to `htmlPath`, hand the live page and context to `run`, and tear
 * everything down afterward.
 *
 * The borrow-versus-launch distinction decides the whole teardown: a supplied
 * browser is borrowed and only its context is closed; a launched one is ours
 * and is closed outright. Shared by every caller that needs a live browser
 * session — `zerp check`'s probe today — so this lifecycle is defined once.
 */
export declare function runBrowserSession<T>(
  options: BrowserSessionOptions,
  run: (page: Page, context: BrowserContext) => Promise<T>,
): Promise<T>;