/**
 * Icon resolution for the .gg pipeline.
 *
 * After parsing, each node.icon is a string identifier. This module
 * walks the DiagramDef and replaces those identifiers with the
 * corresponding raw-SVG fragment (or sets iconError = true).
 *
 * Resolution priority:
 *
 *   1. Built-in namespaces:
 *        'tabler/<name>'         → @tabler/icons outline
 *        'tabler/filled/<name>'  → @tabler/icons filled
 *      (no '@' prefix; built-ins aren't user-aliases)
 *
 *   2. External-file references (paths handled by the loader):
 *        '@alias/x.svg'  → resolved via aliases registered with --alias
 *        './x.svg'       → relative to the .gg file's directory
 *        '/abs/x.svg'    → absolute path
 *        'x.svg'         → relative
 *
 *   3. Bare names (no '/' and no '.svg') → icon map (registered via the
 *      .gg %%{ icons: {…} }%% directive or gridgram.config.ts). The map's
 *      values may be:
 *        - URL ('https://…')           — fetched and inlined at build
 *        - dataURL ('data:image/svg+xml,…') — decoded and inlined
 *        - file path (relative/absolute) — read and inlined
 *        - raw SVG markup ('<svg…>…</svg>') — stripped and inlined
 *
 *   4. Otherwise: iconError = true (the node renders with the red
 *      missing-icon ring).
 */
import type { DiagramDef } from '../types.js';
import type { GgError } from './errors.js';
import type { PlacementDiagnostic } from './diagnostics.js';
export interface IconContext {
    /** Resolved icon map: id → already-loaded SVG content (post URL/dataURL/path resolution). */
    inline?: Record<string, string>;
    /** --icons <dir> → basename → SVG content (already loaded). */
    dir?: Record<string, string>;
    /** Alias name → directory path (for '@alias/x.svg' file references). */
    aliases?: Record<string, string>;
    /** Original path-style icon string → pre-loaded SVG content. */
    paths?: Record<string, string>;
    /**
     * Non-fatal loading errors — per-icon fetch/read/decode failures. The
     * icon resolver silently drops the affected entries (so the node renders
     * with an `iconError` ring rather than aborting the whole diagram), and
     * it's up to the caller to surface these messages. The CLI prints them
     * through formatError; the docs build collects them into its summary.
     */
    errors?: GgError[];
    /**
     * Loader-attributed failures, keyed by the DSL identifier the node
     * would have used (bare name from `doc.icons` or a path-ref string
     * like '@alias/x.svg'). Lets resolveDiagramIcons tell a `load-failed`
     * iconError ("we tried to fetch but …") apart from `not-found`
     * ("no such tabler name / no entry in the icons map"). Populated by
     * the icon-loader as it tries and fails each entry.
     */
    failedSources?: Map<string, string>;
}
/** Strip the outer `<svg>...</svg>` wrapper from a full SVG file. */
export declare function stripSvgWrapper(svg: string): string;
export declare const TABLER_PREFIX = "tabler/";
export declare const TABLER_FILLED_PREFIX = "tabler/filled/";
/**
 * True when `id` is an external-file reference that the loader needs
 * to pre-read (alias-prefixed, ends in a known image extension, or
 * is an absolute / relative path).
 */
export declare function isPathRef(id: string): boolean;
/**
 * Resolve a single icon identifier to either an SVG fragment or an
 * iconError flag.
 */
export declare function resolveIcon(id: string, ctx: IconContext): {
    icon?: string;
    iconError?: boolean;
};
export interface ResolveIconsResult {
    def: DiagramDef;
    /** One PlacementDiagnostic per node.src (or badge.icon) that couldn't
     *  resolve. Reason distinguishes `not-found` (no tabler match / not
     *  registered) from `load-failed` (a loader attempted the source and
     *  got an I/O or network error). */
    diagnostics: PlacementDiagnostic[];
}
/**
 * Walk the DiagramDef, replacing every string-valued node.src (and
 * badge.icon) with the resolved SVG fragment. Unresolvable sources
 * flip `iconError` on the node AND emit a diagnostic with the original
 * src + a best-effort reason.
 */
export declare function resolveDiagramIcons(def: DiagramDef, ctx: IconContext): ResolveIconsResult;
/**
 * Collect every string-form icon reference that looks like an external
 * path. Used by the loader to know which files to pre-read.
 */
export declare function collectPathRefs(def: DiagramDef): string[];
//# sourceMappingURL=icons.d.ts.map