import type { EntityId, Color } from '../core/types';
import type { World, AnimatorComponent, SpriteAnimation } from '../ecs/World';
import type { Renderer2D } from '../rendering/Renderer2D';
/** Minimal icon component contract (matches @nice2dev/icons-gaming) */
export interface IconComponent {
    (props: IconComponentProps): unknown;
    displayName?: string;
}
export interface IconComponentProps {
    size?: number;
    animation?: string;
    color?: string;
    secondaryColor?: string;
}
/** Options for registering an icon as a sprite texture */
export interface IconSpriteOptions {
    /** Render size in px (icons will be rasterized at this resolution) */
    size?: number;
    /** Primary SVG fill color */
    color?: string;
    /** Secondary SVG fill color */
    secondaryColor?: string;
    /** Animation state to bake into the texture (default: 'none') */
    animation?: string;
}
/** Configuration for creating an icon-based entity */
export interface IconEntityOptions extends IconSpriteOptions {
    /** Entity name override (defaults to icon displayName) */
    name?: string;
    /** World position X */
    x?: number;
    /** World position Y */
    y?: number;
    /** Display width in the game world (default: same as size) */
    displayWidth?: number;
    /** Display height in the game world (default: same as size) */
    displayHeight?: number;
    /** Sprite layer for depth sorting */
    layer?: number;
    /** Tint color multiply */
    tint?: Color;
    /** Opacity 0-1 */
    opacity?: number;
}
/** Frame definition for icon animation sheets */
export interface IconAnimationFrame {
    animation: string;
    color?: string;
    secondaryColor?: string;
}
/** Options for creating a multi-frame animation from icon states */
export interface IconAnimationSheetOptions {
    /** Icon size per frame */
    size?: number;
    /** Base color (can be overridden per frame) */
    color?: string;
    /** Frames per second for playback */
    fps?: number;
    /** Whether the animation loops */
    loop?: boolean;
}
/**
 * Render an icon component to an SVG string using React's static markup API.
 * This function must be called with the result of ReactDOMServer.renderToStaticMarkup().
 */
export declare function iconToSvgString(svgMarkup: string, size: number): string;
/**
 * Convert an SVG string to a data URL suitable for Image loading.
 */
export declare function svgToDataUrl(svgString: string): string;
/**
 * Load an SVG data URL into an HTMLImageElement (async).
 */
export declare function loadSvgImage(dataUrl: string): Promise<HTMLImageElement>;
/**
 * Rasterize an SVG string to an OffscreenCanvas / HTMLCanvasElement.
 */
export declare function rasterizeSvg(svgString: string, size: number): Promise<HTMLCanvasElement>;
/**
 * Generate a deterministic texture ID for an icon + options combination.
 */
export declare function getIconTextureId(displayName: string, options?: IconSpriteOptions): string;
/**
 * Register an SVG icon as a texture in the game-engine renderer.
 *
 * @param renderer  The Renderer2D instance
 * @param textureId Unique texture identifier
 * @param svgMarkup Static SVG markup from ReactDOMServer.renderToStaticMarkup(<Icon ... />)
 * @param size      Rasterization size in px
 * @returns         Promise that resolves when the texture is ready
 *
 * @example
 * ```ts
 * import { renderToStaticMarkup } from 'react-dom/server';
 * import { GiWarrior } from '@nice2dev/icons-gaming';
 * import { registerIconTexture, getIconTextureId } from '@nice2dev/game-engine';
 *
 * const id = getIconTextureId('GiWarrior', { size: 64 });
 * const svg = renderToStaticMarkup(<GiWarrior size={64} color="#e74c3c" />);
 * await registerIconTexture(renderer, id, svg, 64);
 * ```
 */
export declare function registerIconTexture(renderer: Renderer2D, textureId: string, svgMarkup: string, size: number): Promise<void>;
/**
 * Register an SVG icon as a rasterized canvas texture (sync-safe after await).
 * Useful when you need pixel-perfect rendering without scaling artifacts.
 */
export declare function registerIconCanvasTexture(renderer: Renderer2D, textureId: string, svgMarkup: string, size: number): Promise<void>;
/**
 * Create a game entity with Sprite component sourced from an icon texture.
 *
 * The texture must already be registered via `registerIconTexture()`.
 *
 * @example
 * ```ts
 * const entityId = createIconEntity(world, 'GiWarrior', textureId, {
 *   x: 200, y: 150, displayWidth: 64, displayHeight: 64, layer: 1,
 * });
 * ```
 */
export declare function createIconEntity(world: World, name: string, textureId: string, options?: Omit<IconEntityOptions, 'size' | 'color' | 'secondaryColor' | 'animation'>): EntityId;
/**
 * Create a SpriteAnimation clip from multiple icon animation frames.
 *
 * Each frame is a separate registered texture. The AnimatorComponent
 * switches `assetId` each frame to show different icon states.
 *
 * @param frames  Array of { assetId, duration } for each frame
 * @param loop    Whether animation loops
 */
export declare function createIconAnimationClip(frames: Array<{
    assetId: string;
    duration?: number;
}>, fps?: number, loop?: boolean): SpriteAnimation;
/**
 * Predefined character animation state sequences.
 * Maps game animation concepts to sets of icon animation states
 * that can be baked into textures.
 */
export declare const CHARACTER_ANIMATION_STATES: readonly ["idle", "move", "jump", "attack-melee", "attack-ranged", "attack-magic", "damage", "death"];
export declare const OBJECT_ANIMATION_STATES: readonly ["idle", "spin", "float", "shake", "glow", "bounce", "flicker"];
/**
 * Batch-register all animation states of an icon as separate textures.
 *
 * @returns Map of animation state → texture ID
 *
 * @example
 * ```ts
 * const textures = await registerIconAnimationSet(
 *   renderer,
 *   'GiWarrior',
 *   (anim) => renderToStaticMarkup(<GiWarrior size={64} animation={anim} color="#e74c3c" />),
 *   CHARACTER_ANIMATION_STATES,
 *   64,
 * );
 * // textures = { idle: 'icon:GiWarrior:s64:aidle', move: 'icon:GiWarrior:s64:amove', ... }
 * ```
 */
export declare function registerIconAnimationSet(renderer: Renderer2D, displayName: string, renderFn: (animation: string) => string, states: readonly string[], size: number): Promise<Record<string, string>>;
/**
 * Create an Animator component configuration from a registered animation set.
 *
 * @param textureMap Result from `registerIconAnimationSet()`
 * @param defaultState Initial animation state (default: 'idle')
 * @param fps Frames per second for each clip
 */
export declare function createIconAnimator(textureMap: Record<string, string>, defaultState?: string, fps?: number): Partial<AnimatorComponent>;
/** Entry in a resolved icon catalog */
export interface IconCatalogEntry {
    name: string;
    textureId: string;
    category: string;
}
/**
 * Register an entire icon map (e.g. `characterIcons`, `weaponIcons`)
 * and return a catalog array for the asset manager / picker.
 *
 * @param renderer   Renderer2D
 * @param iconMap    Map of name→icon render functions (SVG markup generators)
 * @param category   Category label for the asset catalog
 * @param size       Texture size
 *
 * @example
 * ```ts
 * const catalog = await registerIconCatalog(
 *   renderer,
 *   {
 *     GiWarrior: () => renderToStaticMarkup(<GiWarrior size={64} color="#e74c3c" />),
 *     GiMage: () => renderToStaticMarkup(<GiMage size={64} color="#3498db" />),
 *   },
 *   'characters',
 *   64,
 * );
 * ```
 */
export declare function registerIconCatalog(renderer: Renderer2D, iconMap: Record<string, () => string>, category: string, size: number): Promise<IconCatalogEntry[]>;