import { type FetchModule, type SourceIndex } from '@variance-authority/core/attribute';
import type { Page } from 'playwright';
/**
 * Where a component is declared, asked of the engine that ran it.
 *
 * The source scan answers a *name*: every declaration in the configured
 * directories that spells `Button`, and when two do, the name is ambiguous and
 * the report says so. The page holds something better than a name. The fiber
 * carries the function React called, and V8 knows where every function it
 * compiled begins. So the page agent keeps the functions it met (`declared` on
 * the installed global, see `@variance-authority/react`'s `declared.ts`), and
 * this asks Chromium, over CDP, for each one's `[[FunctionLocation]]`. The
 * position is in the served module; the same source maps the call-site path
 * already fetches turn it into a repository file and line.
 *
 * What comes back is a `SourceIndex` with `via: 'engine'`, meant to be laid over
 * the scan with `overlaySourceIndex`: a name the engine located replaces the
 * scan's candidates for it, and a name the engine never met keeps them. The
 * engine can only speak for a component that rendered, which is the half of the
 * question the scan cannot answer and precisely the half a reader of this run
 * needs.
 *
 * Chromium only. `[[FunctionLocation]]` is a V8 internal property and CDP is the
 * road to it; on WebKit and Firefox `newCDPSession` throws, the reader notes it
 * once, and `read()` answers an empty index for the rest of the page's life.
 * Nothing downstream distinguishes that from a page with no components, and
 * nothing should: both are "the engine said nothing", and the scan still stands.
 *
 * A read is incremental. The registry in the page only grows, so each read asks
 * about the functions registered since the last one and returns the union of
 * everything located so far. The registry's `id` changes when the bundle is
 * installed again — a navigation in the route collector — and a changed id
 * starts the count over.
 */
export interface DeclarationReader {
    /** Everything located so far, after asking about what is new. Never throws. */
    read(): Promise<SourceIndex>;
    readonly stats: DeclarationStats;
    /** Detaches the CDP session, if one was ever opened. */
    close(): Promise<void>;
}
export interface DeclarationStats {
    /** Functions the engine was asked about. */
    readonly asked: number;
    /** Of those, the ones that mapped to a file the project wrote. */
    readonly located: number;
}
export interface DeclarationReaderOptions {
    /** The global the page agent is installed at. `AGENT_GLOBAL` unless told otherwise. */
    readonly global?: string;
    /** How served modules are fetched for their maps. From inside the page unless told otherwise. */
    readonly fetchModule?: FetchModule;
    /** Repository root, so the answer is the path the source index speaks. `process.cwd()` unless told otherwise. */
    readonly root?: string;
}
/**
 * A reader over one page's registry. Opens its CDP session on the first read
 * that has something to ask and keeps it until `close`; every read before and
 * after that answers from what it holds. `global` names where the agent is
 * installed, `fetchModule` how served modules are fetched for their maps, and
 * `root` the path an answer is made relative to.
 */
export declare function createDeclarationReader(page: Page, options?: DeclarationReaderOptions): DeclarationReader;
//# sourceMappingURL=declarations.d.ts.map