import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicInformation';
import type { string_color } from '../types/string_person_fullname';
import type { AvatarDefinition } from './types/AvatarDefinition';
import type { AvatarPalette, AvatarSurfaceStyle } from './types/AvatarVisualDefinition';
/**
 * Default square size used by avatar renderers.
 *
 * @private utility of the avatar rendering system
 */
export declare const DEFAULT_AVATAR_SIZE = 192;
/**
 * Normalizes arbitrary agent colors into a stable non-empty color list.
 *
 * @param colors Raw color list.
 * @returns Stable list of usable colors.
 *
 * @private utility of the avatar rendering system
 */
export declare function normalizeAvatarColors(colors: ReadonlyArray<string_color>): ReadonlyArray<string_color>;
/**
 * Normalizes the avatar input so visuals can rely on consistent data.
 *
 * @param avatarDefinition Raw avatar input.
 * @returns Normalized avatar definition.
 *
 * @private utility of the avatar rendering system
 */
export declare function normalizeAvatarDefinition(avatarDefinition: AvatarDefinition): AvatarDefinition;
/**
 * Extracts avatar colors from the flexible `META COLOR` agent field.
 *
 * @param colorValue Raw `META COLOR` value.
 * @returns Parsed avatar colors.
 *
 * @private utility of the avatar rendering system
 */
export declare function parseAvatarColors(colorValue: string | undefined): ReadonlyArray<string_color>;
/**
 * Creates a reusable avatar definition from parsed agent information.
 *
 * @param agentBasicInformation Parsed agent information.
 * @returns Avatar definition ready for canvas rendering.
 *
 * @private shared helper for app-level avatar previews
 */
export declare function createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation: Pick<AgentBasicInformation, 'agentName' | 'agentHash' | 'meta'>): AvatarDefinition;
/**
 * Creates the shared derived palette used by every avatar visual.
 *
 * @param avatarDefinition Stable avatar definition.
 * @param surface Surface style used by the parent UI.
 * @returns Derived palette.
 *
 * @private utility of the avatar rendering system
 */
export declare function createAvatarPalette(avatarDefinition: AvatarDefinition, surface?: AvatarSurfaceStyle): AvatarPalette;
/**
 * Draws the common rounded background frame used by most visuals.
 *
 * @param context Canvas 2D context.
 * @param size Canvas size in CSS pixels.
 * @param palette Derived avatar palette.
 *
 * @private utility of the avatar rendering system
 */
export declare function drawAvatarFrame(context: CanvasRenderingContext2D, size: number, palette: AvatarPalette): void;
/**
 * Creates a rounded rectangle path on the current canvas context.
 *
 * @param context Canvas 2D context.
 * @param x Left coordinate.
 * @param y Top coordinate.
 * @param width Rectangle width.
 * @param height Rectangle height.
 * @param radius Corner radius.
 *
 * @private utility of the avatar rendering system
 */
export declare function createRoundedRectPath(context: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number): void;
/**
 * Creates a stable pseudo-random number generator from a string seed.
 *
 * @param seedSource String seed.
 * @returns Generator producing values in `[0, 1)`.
 *
 * @private utility of the avatar rendering system
 */
export declare function createSeededRandom(seedSource: string): () => number;
/**
 * Creates a deterministic random factory scoped to the avatar definition.
 *
 * @param avatarDefinition Stable avatar definition.
 * @returns Random factory that can be re-seeded per visual part.
 *
 * @private utility of the avatar rendering system
 */
export declare function createAvatarRandomFactory(avatarDefinition: AvatarDefinition): (salt: string) => () => number;
/**
 * Clears and scales the canvas for crisp avatar rendering on high DPI displays.
 *
 * @param canvas Canvas element to prepare.
 * @param context Canvas 2D context.
 * @param size Canvas size in CSS pixels.
 * @param devicePixelRatio Device pixel ratio.
 *
 * @private utility of the avatar rendering system
 */
export declare function prepareAvatarCanvas(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, size: number, devicePixelRatio: number): void;
/**
 * Picks one deterministic element from a non-empty collection.
 *
 * @param items Candidate items.
 * @param random Seeded random generator.
 * @returns Picked item.
 *
 * @private utility of the avatar rendering system
 */
export declare function pickRandomItem<T>(items: ReadonlyArray<T>, random: () => number): T;