/**
 * Component role and refdes planning for CircuitIR device synthesis.
 *
 * Replaces generic `U?` device stubs with a deterministic, traceable
 * component-role plan: a refdes family, a package/footprint hint, and a
 * planning-state marker that differentiates a confidently-classified
 * candidate device from a low-confidence placeholder.
 *
 * By default this module does not select real MPNs, manufacturers, or
 * footprints — it narrows the search space (role + refdes + package family)
 * so a human, BOM-sourcing tool, or downstream planning step can make the
 * final manufacturable selection. Callers may optionally pass a pre-loaded
 * device catalog (`PlanComponentsOptions.catalog` — the starter catalog plus
 * any devices cached by `easyeda_catalog_verify_device`); when a
 * high-confidence role matches a non-obsolete catalog device, that device's
 * MPN/manufacturer/package/LCSC id are used and `planningState` becomes
 * `resolved` instead of `candidate`. See docs/catalog-ingestion.md for what
 * "resolved" does and does not guarantee, and docs/circuit-ir.md for the
 * full synthesis pipeline this module is part of.
 *
 * @module
 */
import type { Block, Device } from './circuit-ir.js';
import { type DeviceEntry } from '../catalog/schema.js';
export type ComponentRole = 'power-regulator' | 'mcu-module' | 'sensor' | 'communication-ic' | 'analog-ic' | 'connector' | 'protection-diode' | 'fuse' | 'passive-support' | 'generic-ic';
/** Confidence that the role was inferred correctly from the DesignIntent block. */
export type RoleConfidence = 'high' | 'low';
export interface ComponentRolePlan {
    role: ComponentRole;
    confidence: RoleConfidence;
}
/** Deterministic refdes family per component role, matching common schematic convention. */
export declare const ROLE_REFDES_PREFIX: Record<ComponentRole, string>;
/** Conservative package/footprint family hint per role — not a final footprint selection. */
export declare const ROLE_PACKAGE_HINT: Record<ComponentRole, string>;
/** Metadata keys the compiler attaches to each planned Device. */
export declare const COMPONENT_PLAN_METADATA_KEYS: {
    readonly role: "role";
    readonly packageHint: "packageHint";
    readonly planningState: "planningState";
    readonly catalogDeviceId: "catalogDeviceId";
};
/**
 * Find the best catalog candidate for a component role, preferring devices
 * with a resolved (non-placeholder) symbol/footprint and a non-empty pin
 * map over ones ingested without an EasyEDA library match (see
 * `src/catalog/ingest.ts`). Returns `undefined` when the role has no
 * catalog-category mapping, no candidates exist, or all candidates are
 * obsolete.
 */
export declare function resolveCandidateDevice(role: ComponentRole, catalog: DeviceEntry[]): DeviceEntry | undefined;
/**
 * Determine a component role for a Block from its `type` and free-text
 * `description` (the compiled block's purpose). Keyword matches on the
 * description take priority over the coarse `type` field because the
 * DesignIntent functional-block `type` is intentionally low-resolution
 * (e.g. "power-management" covers both regulators and passive filter
 * stages).
 */
export declare function determineComponentRole(block: {
    type: string;
    description?: string;
}): ComponentRolePlan;
export interface ComponentPlanResult {
    devices: Device[];
    warnings: string[];
}
export interface PlanComponentsOptions {
    /**
     * A pre-loaded catalog (e.g. the starter catalog plus cached verified
     * devices from `easyeda_catalog_verify_device`) to resolve high-confidence
     * roles against. Omit to preserve the original role/refdes/package-hint-only
     * behavior — this parameter is purely additive and opt-in; existing callers
     * are unaffected.
     */
    catalog?: DeviceEntry[];
}
/**
 * Plan one candidate Device per Block: a deterministic refdes, a component
 * role, and a package-family hint, recorded as Device metadata alongside a
 * `planningState` of `resolved` (a verified catalog device matched the
 * role), `candidate` (role inferred with high confidence but no catalog
 * match), or `placeholder` (role could not be determined; manual
 * classification required).
 *
 * Refdes numbering is deterministic and stable across repeated compiles of
 * the same DesignIntent, because it is derived solely from block order.
 */
export declare function planComponents(blocks: Block[], options?: PlanComponentsOptions): ComponentPlanResult;
/** Read a Device's planned component role back out of its metadata, if present. */
export declare function getDeviceRole(device: Device): ComponentRole | undefined;