/** A raw Figma node as returned by `GET /v1/files/:key/nodes` — provider-shaped, partially typed. */
export interface RawFigmaNode {
    id?: unknown;
    name?: unknown;
    type?: unknown;
    children?: RawFigmaNode[];
    [key: string]: unknown;
}
/** Fetches one node id's subtree at the configured `pageDepth`. Returns undefined on a hard failure
 *  (the caller keeps the shallow content rather than aborting the whole build). */
export type ScopedNodeFetcher = (nodeId: string) => Promise<RawFigmaNode | undefined>;
/**
 * Generic, board-agnostic budgets that bound the per-screen pagination. The global ceiling is the
 * deterministic product `maxScreensDeep × maxNodesPerScreen` (and `× maxFetchesPerScreen`): there is
 * NO shared, live, cross-screen counter, so screens are fully independent and the assembled tree is
 * identical regardless of how the concurrent fetches interleave (load-bearing for the drift hash,
 * #735). None of these is tuned to a sample board; all are overridable per deployment.
 */
export interface ScopedPaginationLimits {
    /** Depth of each individual scoped fetch (the discovery fetch and every per-screen fetch). A larger
     *  depth captures a whole shallow screen in one request and a deep screen in fewer rounds — the
     *  dominant lever against per-request latency — at the cost of larger individual responses. */
    readonly pageDepth: number;
    /** Per-screen raw-node budget; breadth-first expansion stops once a screen reaches it. */
    readonly maxNodesPerScreen: number;
    /** Per-screen fetch cap; bounds requests (and thus wall-clock) for one dense screen. */
    readonly maxFetchesPerScreen: number;
    /** Cap on how many discovered screens are deep-fetched; a board with more reports `capped`. */
    readonly maxScreensDeep: number;
    /**
     * Max in-flight scoped fetches across the WHOLE build (a shared gate over all screens + levels).
     * Real boards have multi-second per-subtree latency, so this pool is the dominant wall-clock lever.
     * It throttles concurrency only — the result is order-independent and deterministic. The 429
     * backoff (#759) absorbs the burst. Clamp ≥ 1.
     */
    readonly fetchConcurrency: number;
}
/**
 * Defaults balanced for Figma's cost-based rate limit on real, latency-bound boards (NOT tuned to any
 * sample board's content). `pageDepth=8` keeps each request cheap enough to avoid provoking sustained
 * 429s; a small shared pool of 3 in-flight fetches parallelises across screens without bursting the
 * limit; the per-screen budgets expand the densest branches further. On a normal board (screens
 * shallower than `pageDepth`) a single per-screen fetch captures everything and no round runs. The
 * 429 backoff (#759) absorbs occasional rate-limit responses; all of these are deployment-overridable.
 */
export declare const DEFAULT_SCOPED_PAGINATION_LIMITS: ScopedPaginationLimits;
/** Coverage telemetry for one deep snapshot fetch — surfaced in the snapshot summary (never a leak). */
export interface FigmaScopeCoverage {
    /** Screens discovered structurally under the scoped root. */
    readonly screenCount: number;
    /** Screens that received a per-screen deep fetch (≤ `maxScreensDeep`). */
    readonly screensDeepFetched: number;
    /** Screens whose deep content was cut short by a per-screen budget (a coverage signal). */
    readonly screensTruncated: number;
    /** Total raw nodes in the assembled deep document. */
    readonly nodeCount: number;
    /** Total per-screen scoped fetches performed (excludes the single discovery fetch). */
    readonly fetchCount: number;
    /** True when more screens were discovered than `maxScreensDeep`, so some stayed shallow. */
    readonly capped: boolean;
}
export interface DeepFetchResult {
    readonly document: RawFigmaNode;
    readonly coverage: FigmaScopeCoverage;
}
/**
 * The screen FRAME/INSTANCE nodes under a scoped root, descending only through container groupings
 * (CANVAS/SECTION) — never into a screen's own body, so a nested frame stays part of its screen.
 * Mirrors the pure-domain `detectScreens` rule (#752) at the connector (raw-node) layer. A directly
 * scoped screen root is the sole screen.
 */
export declare const discoverScreenNodes: (root: RawFigmaNode) => readonly RawFigmaNode[];
/**
 * Deepen a shallow scoped document into a per-screen-paginated one, bounded by {@link limits}.
 * `fetchNode` performs one bounded `depth=pageDepth` scoped fetch (with the connector's 429 backoff).
 * Stays inside the snapshot-build boundary: it issues only scoped node fetches, returns the assembled
 * raw document for the existing deterministic IR cleaner, and reports coverage. A board with no
 * discoverable screen (a directly-scoped non-screen, non-container node) returns the shallow root
 * unchanged with zero-screen coverage.
 */
export declare const paginateScopedDocument: (shallowRoot: RawFigmaNode, fetchNode: ScopedNodeFetcher, limits?: ScopedPaginationLimits) => Promise<DeepFetchResult>;
//# sourceMappingURL=figmaScopedPagination.d.ts.map