/**
 * Person-image role contract.
 *
 * Resolver factories take a role map (`PersonImageRoleMap`) and return a
 * resolver that accepts a `PersonImageInput<Role>`. Roles are typed as a
 * generic string so each application declares its own role names and
 * TypeScript catches unknown role strings at the call site.
 */
/** The gender hint a caller attaches to a record. */
type PersonImageGender = "F" | "M" | null;
/**
 * Per-role image configuration.
 *
 * `default` is required because the resolver must always return a string —
 * a role that has no female/male variant is valid, but a role that has no
 * default would force the resolver to invent a path at runtime.
 */
interface PersonImageRoleDefinition {
    default: string;
    female?: string;
    male?: string;
}
/** A map of role name to its image definition. Keys are the role identifiers. */
type PersonImageRoleMap = Record<string, PersonImageRoleDefinition>;
/** The roles najm-kit ships out of the box. */
type BuiltInPersonImageRole = "child" | "adult" | "parent" | "family";
/**
 * The input a resolver takes.
 *
 * `image` is the value the record actually carries — typically a managed
 * storage URL or `null`/`undefined`. `role` selects which configured map entry
 * applies. `gender` selects the variant inside the role. `fallback` overrides
 * the per-call default and is itself overridden by a real `image`.
 */
interface PersonImageInput<Role extends string> {
    image?: string | null;
    role: Role;
    gender?: PersonImageGender;
    fallback?: string | null;
}
/**
 * A resolver is a function from input to a usable image string.
 *
 * Built around the same input contract as `getPersonImage` so a custom
 * factory returned by `createPersonImageResolver` is interchangeable with the
 * built-in resolver at call sites.
 */
type PersonImageResolver<Role extends string> = (input: PersonImageInput<Role>) => string;

/**
 * The built-in resolver, typed against the four roles najm-kit ships.
 *
 * ```ts
 * const src = getPersonImage({
 *   image: child.image,
 *   role: "child",
 *   gender: child.gender,
 * });
 * ```
 *
 * The four built-in roles are `child`, `adult`, `parent`, and `family`. Any
 * other role string is a type error — applications that need more roles
 * compose their own resolver with `createPersonImageResolver`.
 */
declare const getPersonImage: PersonImageResolver<BuiltInPersonImageRole>;
/**
 * Build a resolver that accepts an application-extended set of role names.
 *
 * The custom map is merged on top of the built-in map, so a key like
 * `teacher` is added while a key like `child` is replaced when the
 * application wants to override the built-in asset. The role union of the
 * returned resolver is the union of the custom keys and the built-in keys
 * that the custom map did not override, so TypeScript still flags unknown
 * role strings at the call site.
 */
declare function createPersonImageResolver<Custom extends Record<string, {
    default: string;
    female?: string;
    male?: string;
}>>(custom: Custom): PersonImageResolver<keyof Custom & string | Exclude<BuiltInPersonImageRole, keyof Custom>>;

/**
 * The default person-image map packaged with najm-kit.
 *
 * Each role is required to have a `default` so a resolver never has to invent
 * a path on the fly: gender is a refinement, not a prerequisite. Female and
 * male variants are optional — when a role is genderless (a household, a
 * neutral family) the same default is used for every gender.
 *
 * The sponsor artwork is intentionally reused as the generic adult artwork:
 * sponsors, staff, applicants, teachers without custom assets, and delivery
 * staff all share the same neutral adult portrait, and the public contract
 * names the role `adult` rather than `sponsor` so other applications can
 * adopt it without re-importing Kafil's vocabulary.
 */
declare const BUILT_IN_PERSON_IMAGE_ROLES: PersonImageRoleMap;

export { BUILT_IN_PERSON_IMAGE_ROLES, type BuiltInPersonImageRole, type PersonImageGender, type PersonImageInput, type PersonImageResolver, type PersonImageRoleDefinition, type PersonImageRoleMap, createPersonImageResolver, getPersonImage };