@jitsusama/agentic-harness.core 0.1.0

package/dist/web/perf/vitals.js

@@ -0,0 +1,175 @@
+/**
+ * What the page cost the person waiting for it.
+ *
+ * The numbers come from the browser's own performance observers,
+ * which is the only place they can honestly come from: largest
+ * contentful paint and layout shift are defined by what the
+ * renderer did, not by anything measurable from outside.
+ *
+ * What this module adds is the arithmetic the observers leave to
+ * the caller, and one piece of it matters more than the rest.
+ * Cumulative layout shift is not the sum of every shift, though
+ * summing is the obvious reading of the name. It is the largest
+ * sum within a session window, so a page that shifts a little
+ * every few seconds over a long visit is not punished as though
+ * it had shifted once, enormously.
+ */
+import { count } from "../../ui/count.js";
+/**
+ * Whether an entry type was actually being watched.
+ *
+ * An observer that never installed reports nothing, which looks
+ * exactly like a page with nothing to report. Cumulative layout
+ * shift is the one that matters: it was pushed unconditionally,
+ * so a capture where no observer ran still answered 0.000 and
+ * PASS, and the renderer's "Nothing was measured" branch could
+ * never be reached.
+ */
+export function watching(vitals, type) {
+    // A capture from before this was recorded says nothing either
+    // way; treat it as watching, which is how it behaved then.
+    return vitals.installed === undefined || vitals.installed.includes(type);
+}
+/** A shift more than this far after the last one starts a new window. */
+export const SESSION_GAP_MS = 1000;
+/** No session window runs longer than this. */
+export const SESSION_CAP_MS = 5000;
+/**
+ * The published good and poor boundaries, in order.
+ *
+ * `longTask` is the per-task pair: a task over 50ms is long, and
+ * the deduction that turns a set of long tasks into total
+ * blocking time is taken against that 50. `tbt` is the separate
+ * pair for the aggregate. Reusing the per-task numbers to rate
+ * the sum called 210ms of total blocking time poor, when the
+ * published boundary for poor is 600, and because perf sits in
+ * the health digest an ordinary page dragged the whole digest
+ * to FAIL.
+ */
+export const THRESHOLDS = {
+    lcp: { good: 2500, poor: 4000 },
+    cls: { good: 0.1, poor: 0.25 },
+    fcp: { good: 1800, poor: 3000 },
+    ttfb: { good: 800, poor: 1800 },
+    longTask: { good: 50, poor: 200 },
+    tbt: { good: 200, poor: 600 },
+};
+/** Rate a measurement against its thresholds. */
+export function rate(value, bounds) {
+    if (value <= bounds.good)
+        return "good";
+    return value <= bounds.poor ? "needs-improvement" : "poor";
+}
+/**
+ * Cumulative layout shift, as the metric is actually defined.
+ *
+ * Shifts are grouped into windows: a gap of a second starts a
+ * new one, and no window runs past five seconds. The score is
+ * the largest window, not the total. Summing everything would
+ * report a page that nudges once a minute as worse than one
+ * that jumps once on load, which is backwards.
+ */
+export function cumulativeShift(shifts) {
+    let worst = 0;
+    let windowTotal = 0;
+    let windowStart = 0;
+    let previous = 0;
+    for (const shift of shifts) {
+        const startsNew = windowTotal > 0 &&
+            (shift.time - previous > SESSION_GAP_MS ||
+                shift.time - windowStart > SESSION_CAP_MS);
+        if (startsNew) {
+            worst = Math.max(worst, windowTotal);
+            windowTotal = 0;
+            windowStart = shift.time;
+        }
+        if (windowTotal === 0)
+            windowStart = shift.time;
+        windowTotal += shift.value;
+        previous = shift.time;
+    }
+    return Math.max(worst, windowTotal);
+}
+/** What most moved the page, and how much. */
+export function worstShiftSources(shifts, limit = 5) {
+    const blame = new Map();
+    for (const shift of shifts) {
+        // A shift with several sources shares its score among them,
+        // because there is no way to tell which one moved the page.
+        const share = shift.sources.length > 0 ? shift.value / shift.sources.length : 0;
+        for (const source of shift.sources) {
+            const node = source.node ?? "(unnamed)";
+            blame.set(node, (blame.get(node) ?? 0) + share);
+        }
+    }
+    return [...blame.entries()]
+        .map(([node, moved]) => ({ node, moved }))
+        .sort((a, b) => b.moved - a.moved)
+        .slice(0, limit);
+}
+/** Read the vitals into rated measures. */
+export function measure(vitals) {
+    const measures = [];
+    const ttfb = vitals.nav?.responseStart;
+    if (ttfb !== undefined) {
+        measures.push({
+            name: "time to first byte",
+            value: ttfb,
+            unit: "ms",
+            rating: rate(ttfb, THRESHOLDS.ttfb),
+        });
+    }
+    const fcp = vitals.paints["first-contentful-paint"];
+    if (fcp !== undefined) {
+        measures.push({
+            name: "first contentful paint",
+            value: fcp,
+            unit: "ms",
+            rating: rate(fcp, THRESHOLDS.fcp),
+        });
+    }
+    if (vitals.lcp) {
+        measures.push({
+            name: "largest contentful paint",
+            value: vitals.lcp.time,
+            unit: "ms",
+            rating: rate(vitals.lcp.time, THRESHOLDS.lcp),
+            ...(vitals.lcp.element === null ? {} : { detail: vitals.lcp.element }),
+        });
+    }
+    const cls = cumulativeShift(vitals.shifts);
+    if (watching(vitals, "layout-shift")) {
+        measures.push({
+            name: "cumulative layout shift",
+            value: Math.round(cls * 1000) / 1000,
+            unit: "score",
+            rating: rate(cls, THRESHOLDS.cls),
+            ...(vitals.shifts.length === 0
+                ? {}
+                : {
+                    detail: count(vitals.shifts.length, "shift"),
+                }),
+        });
+    }
+    const blocking = vitals.longTasks.reduce((sum, task) => sum + Math.max(0, task.duration - THRESHOLDS.longTask.good), 0);
+    // Watched for, not found, is the same rule layout shift follows
+    // and the exact mirror of the bug that rule was written for. A
+    // page that blocked nobody is good news; reporting nothing at
+    // all made it indistinguishable from a page nobody watched, and
+    // two reads of one page could answer four measures and PASS or
+    // five and FAIL with no way to tell which had happened.
+    if (watching(vitals, "longtask")) {
+        measures.push({
+            name: "total blocking time",
+            value: Math.round(blocking),
+            unit: "ms",
+            rating: rate(blocking, THRESHOLDS.tbt),
+            ...(vitals.longTasks.length === 0
+                ? {}
+                : {
+                    detail: count(vitals.longTasks.length, "long task"),
+                }),
+        });
+    }
+    return measures;
+}

package/dist/web/reader.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Page reader: fetches a URL with headless Chrome and captures it as a
+ * bundle of representations the model can pick and choose from.
+ *
+ * Every read settles the page once (capture-width viewport, dynamic-content
+ * wait, lazy-content scroll) and then snapshots article markdown (via
+ * defuddle), the rendered inner text, the DOM and a bounded stack of
+ * screenshot tiles from that one state. Artifacts are written to a private,
+ * per-session directory keyed by process id, so a crashed session's
+ * captures can be reaped without touching a live one. The caller turns the
+ * returned paths into a pointer manifest so the model opens only what it
+ * needs.
+ */
+import type { Page } from "puppeteer-core";
+import { type BundleSink } from "./envelope/sink.js";
+import { type TiledCapture } from "./screenshot.js";
+/**
+ * Thrown when a page redirects to an auth provider and Chrome
+ * cookie injection hasn't been set up yet.
+ */
+export declare class AuthSetupNeeded extends Error {
+    constructor();
+}
+/**
+ * A page captured as a bundle of representations on disk. Each path points
+ * at one representation in `dir`; the model opens whichever it needs. The
+ * DOM is always captured, so `domPath` is required; the article is present
+ * only when extraction found one.
+ */
+export interface PageBundle {
+    title: string;
+    /** The final URL after any redirects, which is what was actually read. */
+    url: string;
+    /** A short inline snippet so the model can judge relevance without opening a file. */
+    excerpt: string;
+    /** The bundle directory holding every artifact. */
+    dir: string;
+    /** Path to the cleaned article markdown, when extraction found an article. */
+    articlePath?: string;
+    /** Path to the rendered inner text, when the page had any. */
+    innerTextPath?: string;
+    /** Path to the rendered DOM (HTML). Always written. */
+    domPath: string;
+    /** Paths to the screenshot tiles, top to bottom. */
+    screenshotPaths: string[];
+    /** True when the page ran past the screenshot tile budget and was cut short. */
+    truncated: boolean;
+}
+/** Extracted article from defuddle: markdown content, title and word count. */
+export interface Article {
+    markdown: string;
+    title: string;
+    wordCount: number;
+}
+/**
+ * The raw representations captured from a settled page, before they are
+ * written to disk. Keeps capture (browser I/O) separate from assembly
+ * (pure file layout) so each is testable on its own.
+ */
+export interface Captured {
+    /** The final URL after redirects. */
+    url: string;
+    title: string;
+    html: string;
+    innerText: string;
+    article: Article | null;
+    /** Base64 PNG tiles, top to bottom. */
+    tiles: string[];
+    truncated: boolean;
+}
+/**
+ * The disk side of bundle assembly, injected so assembly can be tested
+ * without touching the filesystem. Defined in the envelope, since
+ * everything that outgrows a response needs somewhere to go, and
+ * re-exported here for the readers that have always imported it from
+ * this module.
+ */
+export type { BundleSink } from "./envelope/sink.js";
+/** Collaborators of `capturePage`, injected so the orchestration is testable. */
+export interface CaptureDeps {
+    preparePage(page: Page): Promise<void>;
+    captureTiles(page: Page): Promise<TiledCapture>;
+    extractArticle(html: string, url: string): Promise<Article | null>;
+}
+/** True when a final URL indicates a redirect to an auth provider. */
+export declare function isAuthRedirect(url: string): boolean;
+/**
+ * Assemble a bundle from captured representations by writing each one
+ * through the sink. The DOM is always written; the article and inner text
+ * are written only when present; every screenshot tile gets an ordered,
+ * zero-padded name. Text is capped with a visible marker, and the
+ * page-controlled title and excerpt are flattened to a single line so they
+ * cannot impersonate the manifest's own structure.
+ */
+export declare function assembleBundle(captured: Captured, sink: BundleSink): PageBundle;
+export { diskSink } from "./envelope/sink.js";
+/**
+ * Reap bundle directories that no live session owns. The current root is
+ * keyed by process id, so a pid-named directory is abandoned exactly when
+ * its pid is no longer alive; any stray entry there, and the whole legacy
+ * root, are swept by age instead. The collaborators are parameters so the
+ * destructive sweep is testable against a throwaway root.
+ */
+export declare function reapBundles(opts: {
+    root: string;
+    legacyRoots: readonly string[];
+    isPidAlive: (pid: number) => boolean;
+    now: number;
+    legacyMaxAgeMs: number;
+}): void;
+/**
+ * Reap bundle directories left behind by sessions that are no longer
+ * running. Safe to call at session start; it never touches a live
+ * session's directory.
+ */
+export declare function reapAbandonedBundles(): void;
+/** Remove this session's bundle directory. Call at session shutdown. */
+export declare function cleanupSessionBundles(): void;
+/**
+ * Navigate a prepared page and capture every representation from one
+ * settled state: DOM, inner text, article and screenshot tiles. Relative
+ * links resolve against the final redirected URL, and a missing document
+ * body falls back to the document text so non-HTML pages still yield a
+ * capture. Cancellation is honoured between the expensive steps.
+ */
+export declare function capturePage(page: Page, url: string, signal?: AbortSignal, deps?: CaptureDeps): Promise<Captured>;
+/**
+ * Fetch a URL and capture it as a bundle of representations on disk:
+ * article markdown, rendered inner text, DOM and screenshot tiles.
+ */
+export declare function readPage(url: string, signal?: AbortSignal): Promise<PageBundle>;

package/dist/web/reader.js

@@ -0,0 +1,340 @@
+/**
+ * Page reader: fetches a URL with headless Chrome and captures it as a
+ * bundle of representations the model can pick and choose from.
+ *
+ * Every read settles the page once (capture-width viewport, dynamic-content
+ * wait, lazy-content scroll) and then snapshots article markdown (via
+ * defuddle), the rendered inner text, the DOM and a bounded stack of
+ * screenshot tiles from that one state. Artifacts are written to a private,
+ * per-session directory keyed by process id, so a crashed session's
+ * captures can be reaped without touching a live one. The caller turns the
+ * returned paths into a pointer manifest so the model opens only what it
+ * needs.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Defuddle } from "defuddle/node";
+import { JSDOM, VirtualConsole } from "jsdom";
+import { isPidAlive, newPage } from "./browser.js";
+import { injectCookies, isSetUp } from "./cookies/index.js";
+import { BUNDLE_ROOT, diskSink, LEGACY_BUNDLE_ROOTS, sessionDir, } from "./envelope/sink.js";
+import { captureTiles, preparePage } from "./screenshot.js";
+/**
+ * Thrown when a page redirects to an auth provider and Chrome
+ * cookie injection hasn't been set up yet.
+ */
+export class AuthSetupNeeded extends Error {
+    constructor() {
+        super("This page requires authentication. Ask the user to run " +
+            "Chrome cookie setup to enable access using their Chrome " +
+            "browser sessions, then retry.");
+        this.name = "AuthSetupNeeded";
+    }
+}
+/** Timeout for page navigation in milliseconds. */
+const PAGE_LOAD_TIMEOUT = 20_000;
+/** Wait time for dynamic content to render after load. */
+const DYNAMIC_CONTENT_WAIT = 1_500;
+/** Characters of the best available text used for the inline excerpt. */
+const EXCERPT_LENGTH = 500;
+/** Below this word count we treat defuddle's article as empty and skip it. */
+const MIN_ARTICLE_WORDS = 30;
+/** Upper bound on the page-controlled title we carry inline. */
+const MAX_TITLE_LENGTH = 300;
+/**
+ * Upper bound on any single text artifact written to disk. Generous enough
+ * that real pages are never touched, but it caps a pathological page so it
+ * cannot fill the disk. When it bites, the file says so in-band rather than
+ * ending silently.
+ */
+const MAX_ARTIFACT_CHARS = 5_000_000;
+/** Age past which a legacy bundle directory is reaped. */
+const LEGACY_MAX_AGE_MS = 6 * 60 * 60 * 1_000;
+/** URL fragments that mark a redirect to an auth provider. */
+const AUTH_URL_MARKERS = [
+    "accounts.google.com",
+    "/oauth",
+    "/login",
+    "/signin",
+    "/auth",
+];
+/**
+ * Lines matching these patterns are stripped from the rendered inner
+ * text after extraction.
+ */
+const BOILERPLATE_PATTERNS = [
+    /^advertisement$/i,
+    /^ad$/i,
+    /^sponsored$/i,
+    /^continue reading/i,
+    /^read more$/i,
+    /^see also:?$/i,
+    /^related:?$/i,
+    /^share this/i,
+    /^follow us/i,
+    /^sign up for/i,
+    /^subscribe to/i,
+    /^newsletter/i,
+    /^click here/i,
+];
+/** True when a final URL indicates a redirect to an auth provider. */
+export function isAuthRedirect(url) {
+    return AUTH_URL_MARKERS.some((marker) => url.includes(marker));
+}
+/** Collapse a page-controlled string to a single trimmed line. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Cap a text artifact at the size bound, appending a visible marker when it
+ * bites so a reader never mistakes a cut-off file for a complete one.
+ */
+function capArtifact(content) {
+    if (content.length <= MAX_ARTIFACT_CHARS)
+        return content;
+    return `${content.slice(0, MAX_ARTIFACT_CHARS)}\n\n[truncated at ${MAX_ARTIFACT_CHARS} characters]`;
+}
+/**
+ * Assemble a bundle from captured representations by writing each one
+ * through the sink. The DOM is always written; the article and inner text
+ * are written only when present; every screenshot tile gets an ordered,
+ * zero-padded name. Text is capped with a visible marker, and the
+ * page-controlled title and excerpt are flattened to a single line so they
+ * cannot impersonate the manifest's own structure.
+ */
+export function assembleBundle(captured, sink) {
+    const title = oneLine(captured.title).slice(0, MAX_TITLE_LENGTH);
+    const body = captured.article?.markdown || captured.innerText;
+    const excerpt = oneLine(body).slice(0, EXCERPT_LENGTH);
+    const articlePath = captured.article
+        ? sink.writeText("article.md", capArtifact(`# ${title}\n\nSource: ${captured.url}\n\n${captured.article.markdown}`))
+        : undefined;
+    const innerTextPath = captured.innerText
+        ? sink.writeText("innertext.txt", capArtifact(captured.innerText))
+        : undefined;
+    const domPath = sink.writeText("dom.html", capArtifact(captured.html));
+    const screenshotPaths = captured.tiles.map((data, i) => sink.writeBinary(`shot-${String(i + 1).padStart(2, "0")}.png`, data));
+    return {
+        title,
+        url: captured.url,
+        excerpt,
+        dir: sink.dir,
+        articlePath,
+        innerTextPath,
+        domPath,
+        screenshotPaths,
+        truncated: captured.truncated,
+    };
+}
+/** Clean extracted text: collapse whitespace, strip boilerplate lines. */
+function cleanText(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return true;
+        return !BOILERPLATE_PATTERNS.some((p) => p.test(trimmed));
+    })
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Create a jsdom VirtualConsole that suppresses CSS parse warnings
+ * without affecting process.stderr globally.
+ */
+function quietVirtualConsole() {
+    const vc = new VirtualConsole();
+    vc.on("error", (msg) => {
+        if (!msg.includes("Could not parse CSS stylesheet")) {
+            console.error(msg);
+        }
+    });
+    vc.on("warn", console.warn);
+    vc.on("info", console.info);
+    return vc;
+}
+/**
+ * Run defuddle over the page HTML to extract the main content as markdown,
+ * resolving relative links against the final URL. Returns null when
+ * defuddle throws or finds too little to be a real article.
+ */
+async function extractArticle(html, url) {
+    try {
+        const dom = new JSDOM(html, { url, virtualConsole: quietVirtualConsole() });
+        const result = await Defuddle(dom.window.document, url, {
+            markdown: true,
+            useAsync: false,
+        });
+        if (!result || result.wordCount < MIN_ARTICLE_WORDS)
+            return null;
+        return {
+            markdown: result.contentMarkdown ?? result.content ?? "",
+            title: result.title ?? "",
+            wordCount: result.wordCount,
+        };
+    }
+    catch {
+        // Defuddle or JSDOM threw (e.g., CSS parse errors on a hostile
+        // page). Article extraction is optional; the bundle still has the
+        // inner text, DOM and screenshots, so we report no article.
+        return null;
+    }
+}
+export { diskSink } from "./envelope/sink.js";
+/** True when a directory's mtime is older than the given age. */
+function olderThan(dir, now, maxAgeMs) {
+    try {
+        return now - fs.statSync(dir).mtimeMs > maxAgeMs;
+    }
+    catch {
+        // The directory vanished under us; treat it as not stale.
+        return false;
+    }
+}
+/** Remove immediate subdirectories of `root` for which `stale` returns true. */
+function reapDir(root, stale) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        // The root does not exist, so there is nothing to reap.
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        try {
+            if (stale(dir, entry.name))
+                fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // The directory vanished under us or is unreadable; skip it.
+        }
+    }
+}
+/**
+ * Reap bundle directories that no live session owns. The current root is
+ * keyed by process id, so a pid-named directory is abandoned exactly when
+ * its pid is no longer alive; any stray entry there, and the whole legacy
+ * root, are swept by age instead. The collaborators are parameters so the
+ * destructive sweep is testable against a throwaway root.
+ */
+export function reapBundles(opts) {
+    reapDir(opts.root, (dir, name) => {
+        const pid = Number(name);
+        // A pid-named dir is abandoned when its process is gone; any other
+        // entry (e.g. from an older layout) has no owner, so fall back to age.
+        return Number.isInteger(pid)
+            ? !opts.isPidAlive(pid)
+            : olderThan(dir, opts.now, opts.legacyMaxAgeMs);
+    });
+    for (const legacy of opts.legacyRoots) {
+        // By age rather than by pid, even where the old layout named its
+        // directories after one: nothing writes here any more, so an
+        // entry whose pid happens to be alive again belongs to an
+        // unrelated process that reused the number.
+        reapDir(legacy, (dir) => olderThan(dir, opts.now, opts.legacyMaxAgeMs));
+    }
+}
+/**
+ * Reap bundle directories left behind by sessions that are no longer
+ * running. Safe to call at session start; it never touches a live
+ * session's directory.
+ */
+export function reapAbandonedBundles() {
+    reapBundles({
+        root: BUNDLE_ROOT,
+        legacyRoots: LEGACY_BUNDLE_ROOTS,
+        isPidAlive,
+        now: Date.now(),
+        legacyMaxAgeMs: LEGACY_MAX_AGE_MS,
+    });
+}
+/** Remove this session's bundle directory. Call at session shutdown. */
+export function cleanupSessionBundles() {
+    try {
+        fs.rmSync(sessionDir(), { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup; the reaper reclaims it later if this fails.
+    }
+}
+/** Throw if the operation has been cancelled. */
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new Error("Aborted");
+}
+const defaultCaptureDeps = {
+    preparePage,
+    captureTiles,
+    extractArticle,
+};
+/**
+ * Navigate a prepared page and capture every representation from one
+ * settled state: DOM, inner text, article and screenshot tiles. Relative
+ * links resolve against the final redirected URL, and a missing document
+ * body falls back to the document text so non-HTML pages still yield a
+ * capture. Cancellation is honoured between the expensive steps.
+ */
+export async function capturePage(page, url, signal, deps = defaultCaptureDeps) {
+    await page.goto(url, {
+        waitUntil: "domcontentloaded",
+        timeout: PAGE_LOAD_TIMEOUT,
+    });
+    throwIfAborted(signal);
+    await page.evaluate((ms) => new Promise((r) => setTimeout(r, ms)), DYNAMIC_CONTENT_WAIT);
+    const finalUrl = page.url();
+    if (isAuthRedirect(finalUrl) && !isSetUp()) {
+        throw new AuthSetupNeeded();
+    }
+    throwIfAborted(signal);
+    // Settle the page once so text, DOM and screenshots agree on one state.
+    await deps.preparePage(page);
+    const html = await page.content();
+    const rendered = cleanText(await page.evaluate(() => document.body?.innerText ?? document.documentElement?.textContent ?? ""));
+    const article = await deps.extractArticle(html, finalUrl);
+    const title = article?.title || (await page.title());
+    throwIfAborted(signal);
+    // Screenshots are always captured so a text-only bundle still carries a
+    // visual representation the model can fall back to.
+    const { tiles, truncated } = await deps.captureTiles(page);
+    throwIfAborted(signal);
+    return {
+        url: finalUrl,
+        title,
+        html,
+        innerText: rendered,
+        article,
+        tiles,
+        truncated,
+    };
+}
+/**
+ * Fetch a URL and capture it as a bundle of representations on disk:
+ * article markdown, rendered inner text, DOM and screenshot tiles.
+ */
+export async function readPage(url, signal) {
+    const page = await newPage();
+    try {
+        throwIfAborted(signal);
+        await injectCookies(page, url);
+        const captured = await capturePage(page, url, signal);
+        const sink = diskSink();
+        try {
+            return assembleBundle(captured, sink);
+        }
+        catch (err) {
+            // Don't leave a half-written bundle behind on a failed assembly.
+            fs.rmSync(sink.dir, { recursive: true, force: true });
+            throw err;
+        }
+    }
+    finally {
+        await page.close();
+    }
+}

package/dist/web/screenshot.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Bounded, tiled screenshot capture.
+ *
+ * `preparePage` settles the page (capture-width viewport, lazy-content
+ * scroll) so every representation is read from one state. `captureTiles`
+ * then captures the page as an ordered stack of vertical bands rather than
+ * one full-page image. Each band stays under the model provider's image
+ * dimension limit, so a long page can never produce an image the model
+ * rejects. A page taller than the tile budget is truncated and the caller
+ * is told.
+ */
+import type { Page } from "puppeteer-core";
+/** A vertical slice of the page to capture, in page pixels. */
+export interface TileBand {
+    y: number;
+    height: number;
+}
+/** An ordered set of clip bands covering a page, with a truncation flag. */
+export interface TilePlan {
+    bands: TileBand[];
+    truncated: boolean;
+}
+/**
+ * Plan the vertical clip bands that tile a page of the given height. No
+ * band exceeds `bandHeight`, and the plan stops at `maxTiles`, reporting
+ * `truncated` when the page runs past the tile budget.
+ */
+export declare function planTiles(pageHeight: number, opts: {
+    bandHeight: number;
+    maxTiles: number;
+}): TilePlan;
+/** A tiled capture: ordered base64 PNGs plus whether the page overran the budget. */
+export interface TiledCapture {
+    tiles: string[];
+    truncated: boolean;
+}
+/**
+ * Settle the page into the state every representation is captured from:
+ * fix the viewport to the capture width, then scroll to the bottom so
+ * lazy-loaded content renders, returning to the top. Call this once before
+ * reading the DOM, inner text or screenshots so they all agree.
+ */
+export declare function preparePage(page: Page): Promise<void>;
+/**
+ * Capture the page as an ordered stack of PNG tiles, each a base64 string,
+ * by clipping successive vertical bands planned by `planTiles`. No tile
+ * exceeds the band height, and the capture stops at the tile ceiling.
+ * Assumes `preparePage` has already settled the viewport and lazy content.
+ */
+export declare function captureTiles(page: Page): Promise<TiledCapture>;