import type { AdapterContext, DesignReference, ReferenceAdapter, SiblingTarget, Theme } from "@design-parity/core";
import type { ReferenceCache } from "./reference-cache.js";
import { type FigmaRef } from "./figma-ref.js";
import { FigmaRestClient, type FetchLike } from "./rest-client.js";
/** One image to render: a node, tagged with the variant it represents. */
export interface RenderTarget {
    nodeId: string;
    state?: string;
    theme?: Theme;
    size?: string;
}
export interface FigmaAdapterOptions {
    /** Pre-built client (tests inject this). Overrides `fetch`/`baseUrl`. */
    client?: FigmaRestClient;
    /** Injectable fetch used when building a client from `ctx.env`. */
    fetch?: FetchLike;
    /** API base override (tests). */
    baseUrl?: string;
    /**
     * Attempts per REST request before a 429/5xx is raised. Defaults to the
     * client's own default; 1 disables retrying, which is what a test asserting
     * the error mapping wants.
     */
    attempts?: number;
    /** Injectable delay for the retry backoff (tests). */
    sleep?: (ms: number) => Promise<void>;
    /** Directory rendered references are written to. Defaults under the repo root. */
    outDir?: string;
    /** Image render scale (Figma `scale`, PNG only). Defaults to 2. */
    imageScale?: number;
    /**
     * Reference image format. `svg` (default) imports the design as resolution-free
     * vector — crisp in the report, rasterised on the fly for the pixel diff; `png`
     * keeps the legacy raster export at {@link FigmaAdapterOptions.imageScale}.
     */
    imageFormat?: "png" | "svg";
    /**
     * Whether Figma exports only the referenced node's own contents. Defaults to
     * true; false includes overlapping layers, such as a component-sheet backdrop.
     */
    imageContentsOnly?: boolean;
    /** Code Connect JSON to consult when `ref` is not a figma handle. */
    codeConnectPath?: string;
    /**
     * A committed reference cache (see `reference-cache.ts`) to read structure,
     * variables and reference images from instead of calling Figma.
     *
     * A hit costs no request at all; a miss falls through to the API, so adding a
     * cache can only reduce the calls a run makes. Pair with
     * {@link FigmaAdapterOptions.cacheOnly} for the guarantee rather than the
     * tendency.
     */
    cache?: ReferenceCache;
    /**
     * Make the cache the ONLY reference source: a miss raises
     * {@link FigmaCacheMissError} rather than reaching for the network.
     *
     * This is what a parity run on a code change wants. Zero Figma calls means no
     * rate limit and no network flake, and the diff is reproducible because the
     * reference is pinned to what the last import saw rather than to whatever the
     * file happens to say at the moment the job runs. A miss is a per-component
     * error the run already fails soft on — one honest gap on a board, not a
     * silently dropped row.
     */
    cacheOnly?: boolean;
    /**
     * Produce the render targets for a resolved ref — e.g. one node per theme.
     * Defaults to a single image of the ref's node with no theme/size tag.
     */
    resolveTargets?: (ref: FigmaRef, ctx: AdapterContext) => RenderTarget[] | Promise<RenderTarget[]>;
}
export declare class FigmaAdapter implements ReferenceAdapter {
    #private;
    readonly source: "figma";
    constructor(opts?: FigmaAdapterOptions);
    /**
     * Read every node the run will need, in as few requests as the API allows.
     *
     * `GET /v1/files/:key/nodes` takes a list, and the client has always accepted
     * one — but `resolve` runs per component and asked for a single id each time,
     * so a 77-component catalog made 77 requests for something two would have
     * carried. Against a per-token limiter that is the difference between a run
     * that completes and one that loses most of its references to 429s.
     *
     * Best-effort by contract: a chunk that fails is left out of the cache and
     * `resolve` fetches it alone, so a partial warm degrades to today's behaviour
     * rather than failing the run.
     */
    prefetch(refs: readonly string[], ctx: AdapterContext): Promise<void>;
    /**
     * The same component with one variant axis moved — `Size=Small` →
     * `Size=Medium` — as a `figma:<fileKey>/<nodeId>` handle.
     *
     * A component set's variant names are axis vectors and every child names
     * every axis, so this is a lookup in the set's children rather than a guess.
     * That makes it Figma's data model, not any consumer's taxonomy, which is why
     * it belongs on the adapter: every consumer comparing more than a default
     * state needs it.
     *
     * Returns `undefined` — deliberately, and for every failure alike: the ref is
     * not a Figma handle, the node is not a variant, its set could not be read,
     * the axis is not one this component has, or no sibling carries that value. A
     * translation the source does not have must find *nothing*, because the
     * alternative is a confident reference to the wrong node.
     */
    resolveSibling(ref: string, target: SiblingTarget, ctx: AdapterContext): Promise<string | undefined>;
    resolve(componentId: string, ref: string, ctx: AdapterContext): Promise<DesignReference>;
}
/** Convenience factory. */
export declare function createFigmaAdapter(opts?: FigmaAdapterOptions): FigmaAdapter;
//# sourceMappingURL=adapter.d.ts.map