<?php
/**
 * File Path: includes/helpers/class-mbs-cover-strategy.php
 *
 * Cover Strategy Interface
 *
 * Contract for all cover resolution strategies used by MBS_Cover_Renderer.
 * Each strategy attempts to resolve a cover for a given book/format and returns
 * a non-empty HTML string on success, or an empty string when the strategy
 * does not apply.
 *
 * Strategies are evaluated in priority order by MBS_Cover_Renderer::render().
 * The first strategy that returns a non-empty string wins; the chain stops.
 *
 * @package    My_Book_Showroom
 * @subpackage Includes/Helpers
 * @since      1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

interface MBS_Cover_Strategy { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedInterfaceFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Attempt to resolve the cover HTML for the given book/format.
	 *
	 * Implementations must return a non-empty HTML string when the strategy
	 * applies, or an empty string '' when it does not. Must never return null
	 * or throw — callers rely on the empty-string contract to continue the chain.
	 *
	 * @param int         $post_id    Book post ID.
	 * @param object|null $format_row Format row object from MBS_Format_Row_DAO (optional).
	 * @return string  Non-empty escaped HTML when resolved; '' when not applicable.
	 */
	public static function resolve( int $post_id, ?object $format_row ): string;
}
