<?php
declare(strict_types=1);

/**
 * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
 *
 * Contract for image composers that turn raw provider bytes into final variants.
 *
 * A composer sits between the image provider (raw generated bytes) and the
 * media sideloader. It receives one base image plus per-post context and
 * returns one or more finished variants — the first is always the `featured`
 * role (the bytes that become the post thumbnail), optionally followed by
 * social variants (`og`, `square`). Implementations must NEVER throw out of
 * compose(): on any internal failure they degrade to passing the base image
 * through unmodified so publishing is never blocked.
 *
 * Triggered by: PRAutoBlogger_Image_Pipeline between batch results and sideload.
 * Dependencies: none — this is the contract only.
 *
 * @see core/class-image-composer.php  — Default implementation (capability ladder).
 * @see core/class-image-pipeline.php  — Caller.
 * @see core/class-image-attacher.php  — Persists the returned variants.
 */
interface PRAutoBlogger_Image_Composer_Interface {

	/**
	 * Compose final image variant(s) from raw provider bytes.
	 *
	 * Side effects: implementations may read plugin options and write to the
	 * activity log; they must not make network calls or fail the publish.
	 *
	 * @param array{
	 *     bytes: string,
	 *     mime_type: string,
	 *     width: int,
	 *     height: int,
	 * } $image_data Base image bytes + metadata from the provider result.
	 * @param array{
	 *     post_id: int,
	 *     caption: string,
	 *     title: string,
	 *     slot: string,
	 * } $context Post ID, editorial caption, post title, and slot
	 *            ('image_a' or 'image_b'); only image_a yields variants.
	 *
	 * @return array<int, array{bytes: string, mime_type: string, width: int, height: int, role: string}>
	 *               Non-empty list; index 0 always carries role 'featured'.
	 */
	public function compose( array $image_data, array $context ): array;
}