<?php

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

/** Free-edition administration and the shared Profile A settings contract. */
final class AI_Narration_Admin {
	private const PAGE_SLUG = 'ai-narration';
	private const SCREEN_ID = 'toplevel_page_ai-narration';
	private const PAGE_SIZE = 25;
	private const ADMIN_ASSET_VERSION = '1.2.0-beta.3';
	private const GETTING_STARTED_PREVIEW_META_KEY = '_ai_narration_free_getting_started_voice_previewed';
	private const GETTING_STARTED_PLAYER_META_KEY = '_ai_narration_free_getting_started_player_confirmed';

	private AI_Narration_Content $content;
	private AI_Narration_Cache $cache;

	public function __construct( AI_Narration_Content $content, AI_Narration_Cache $cache ) {
		$this->content = $content;
		$this->cache   = $cache;

		add_action( 'admin_menu', array( $this, 'add_settings_page' ) );
		add_filter( 'plugin_row_meta', array( $this, 'add_plugin_row_meta' ), 10, 2 );
		add_action( 'admin_bar_menu', array( $this, 'add_admin_bar_menu' ), 90 );
		add_action( 'admin_init', array( $this, 'register_settings' ) );
		add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_settings_assets' ) );
		add_filter( 'admin_body_class', array( $this, 'admin_body_class' ) );
		add_action( 'add_meta_boxes', array( $this, 'add_meta_boxes' ) );
		add_action( 'save_post', array( $this, 'save_post_override' ) );
		add_action( 'admin_post_ai_narration_run_queue_now', array( $this, 'run_queue_now' ) );
		add_action( 'admin_post_ai_narration_retry_failed', array( $this, 'retry_failed' ) );
		add_action( 'admin_post_ai_narration_confirm_public_player', array( $this, 'confirm_public_player' ) );
		add_action( 'wp_ajax_ai_narration_free_status', array( $this, 'free_status' ) );
	}

	/** @return array<string,mixed> */
	public static function default_settings(): array {
		return array(
			'api_key'                   => '',
			'narration_provider'         => 'openai',
			'model'                     => 'gpt-4o-mini-tts',
			'voice'                     => 'cedar',
			'instructions'              => '',
			'read_h2_headings'          => false,
			'auto_generate'             => true,
			'post_types'                => array(),
			'categories'                => array(),
			'player_preset'             => 'light',
		);
	}

	/** Preserve every unknown saved key so moving between editions is reversible. @return array<string,mixed> */
	public static function get_settings(): array {
		$saved = get_option( 'ai_narration_settings', array() );
		$saved = is_array( $saved ) ? $saved : array();
		$settings = wp_parse_args( $saved, self::default_settings() );

		// The WordPress.org edition supports OpenAI. Unknown saved keys remain in
		// the shared option so changing editions does not destroy existing data.
		$settings['narration_provider'] = 'openai';
		$settings['model'] = array_key_exists( (string) $settings['model'], self::models() ) ? (string) $settings['model'] : 'gpt-4o-mini-tts';
		$settings['voice'] = array_key_exists( (string) $settings['voice'], self::voices() ) ? (string) $settings['voice'] : 'cedar';
		$settings['read_h2_headings'] = ! empty( $settings['read_h2_headings'] );
		$settings['auto_generate'] = ! empty( $settings['auto_generate'] );
		$settings['player_preset'] = in_array( (string) $settings['player_preset'], array( 'light', 'dark' ), true ) ? (string) $settings['player_preset'] : 'light';
		return $settings;
	}

	public static function get_api_key(): string {
		if ( defined( 'AI_NARRATION_OPENAI_API_KEY' ) && is_string( AI_NARRATION_OPENAI_API_KEY ) ) {
			return trim( AI_NARRATION_OPENAI_API_KEY );
		}
		return trim( (string) ( self::get_settings()['api_key'] ?? '' ) );
	}

	public static function has_api_key(): bool { return '' !== self::get_api_key(); }

	/** Record a successful Free narration voice preview for the current administrator. */
	public static function mark_voice_previewed(): void {
		$user_id = get_current_user_id();
		if ( $user_id > 0 ) {
			update_user_meta( $user_id, self::GETTING_STARTED_PREVIEW_META_KEY, '1' );
		}
	}

	public static function narration_provider(): string { return 'openai'; }

	public static function has_narration_credentials(): bool {
		return self::has_api_key();
	}

	public static function narration_provider_label(): string { return 'OpenAI'; }

	public static function automatic_cache_generation(): bool {
		return ! empty( self::get_settings()['auto_generate'] );
	}
	public static function player_heading(): string { return __( 'Listen', 'ai-narration' ); }
	public static function show_idle_duration(): bool { return true; }
	public static function player_disclosure(): string { return __( 'AI Narration', 'ai-narration' ); }

	/** @param array<string,string|int> $query_args */
	public static function settings_url( array $query_args = array() ): string {
		$url = admin_url( 'admin.php?page=' . self::PAGE_SLUG );
		return empty( $query_args ) ? $url : add_query_arg( $query_args, $url );
	}

	public static function player_style_attribute(): string {
		$preset = (string) self::get_settings()['player_preset'];
		$styles = array( '--ai-narration-radius:16px' );
		if ( 'light' === $preset ) {
			$styles[] = '--ai-narration-background:#f6f7f7';
			$styles[] = '--ai-narration-color:#3c434a';
			$styles[] = '--ai-narration-border-color:#c3c4c7';
		} elseif ( 'dark' === $preset ) {
			$styles[] = '--ai-narration-background:#202125';
			$styles[] = '--ai-narration-color:#c3c4c7';
			$styles[] = '--ai-narration-border-color:#3c434a';
		}
		return implode( ';', $styles );
	}

	public function add_settings_page(): void {
		add_menu_page( __( 'AI Narration', 'ai-narration' ), __( 'AI Narration', 'ai-narration' ), 'manage_options', self::PAGE_SLUG, array( $this, 'render_settings_page' ), 'dashicons-controls-volumeon', 81 );
	}

	/** @param array<int,string> $plugin_meta @return array<int,string> */
	public function add_plugin_row_meta( array $plugin_meta, string $plugin_file ): array {
		if ( plugin_basename( AI_NARRATION_FILE ) !== $plugin_file ) {
			return $plugin_meta;
		}

		if ( current_user_can( 'manage_options' ) ) {
			array_unshift( $plugin_meta, '<a href="' . esc_url( self::settings_url() ) . '">' . esc_html__( 'Settings', 'ai-narration' ) . '</a>' );
		}

		return $plugin_meta;
	}

	public function add_admin_bar_menu( WP_Admin_Bar $admin_bar ): void {
		if ( current_user_can( 'manage_options' ) ) {
			$admin_bar->add_node( array( 'id' => 'ai-narration-settings', 'title' => __( 'AI Narration', 'ai-narration' ), 'href' => self::settings_url() ) );
		}
	}

	public function enqueue_settings_assets( string $hook_suffix ): void {
		if ( self::SCREEN_ID !== $hook_suffix ) { return; }
		wp_enqueue_style( 'ai-narration-player-preview', AI_NARRATION_URL . 'assets/player-v4.0.0.css', array(), self::ADMIN_ASSET_VERSION );
		wp_enqueue_style( 'ai-narration-admin', AI_NARRATION_URL . 'assets/admin.css', array( 'ai-narration-player-preview' ), self::ADMIN_ASSET_VERSION );
		wp_enqueue_script( 'ai-narration-admin', AI_NARRATION_URL . 'assets/admin.js', array(), self::ADMIN_ASSET_VERSION, true );
		wp_localize_script(
			'ai-narration-admin',
			'AINarrationAdmin',
			array(
				'ajaxUrl' => admin_url( 'admin-ajax.php' ),
				'voicePreviewNonce' => wp_create_nonce( 'ai_narration_voice_preview' ),
				'statusNonce' => wp_create_nonce( 'ai_narration_free_status' ),
				'statusPollInterval' => 1500,
				'strings' => array(
					'play' => __( 'Play', 'ai-narration' ),
					'pause' => __( 'Pause', 'ai-narration' ),
					'preview' => __( 'Preview selected voice', 'ai-narration' ),
					'preparing' => __( 'Preparing preview…', 'ai-narration' ),
					'stop' => __( 'Stop preview', 'ai-narration' ),
					'error' => __( 'The voice preview could not be prepared.', 'ai-narration' ),
					'copied' => __( 'Copied', 'ai-narration' ),
				),
			)
		);
	}

	public function admin_body_class( string $classes ): string {
		$screen = get_current_screen();
		return $screen && self::SCREEN_ID === $screen->id ? $classes . ' ai-narration-admin-settings-page ai-narration-admin-theme-light' : $classes;
	}

	public function register_settings(): void {
		register_setting( 'ai_narration_group', 'ai_narration_settings', array( 'type' => 'array', 'sanitize_callback' => array( $this, 'sanitize_settings' ), 'default' => self::default_settings() ) );
	}

	/** @param mixed $input @return array<string,mixed> */
	public function sanitize_settings( $input ): array {
		$input = is_array( $input ) ? $input : array();
		$raw = get_option( 'ai_narration_settings', array() );
		$output = is_array( $raw ) ? $raw : array();
		$existing = self::get_settings();

		$this->save_key( $output, $input, 'api_key', 'clear_api_key', defined( 'AI_NARRATION_OPENAI_API_KEY' ) );
		$model = sanitize_key( (string) ( $input['model'] ?? '' ) );
		$output['model'] = array_key_exists( $model, self::models() ) ? $model : (string) $existing['model'];
		$voice = sanitize_key( (string) ( $input['voice'] ?? '' ) );
		$output['voice'] = array_key_exists( $voice, self::voices() ) ? $voice : (string) $existing['voice'];
		$output['instructions'] = $this->limit_string( sanitize_textarea_field( (string) ( $input['instructions'] ?? $existing['instructions'] ) ), 4096 );

		$output['read_h2_headings'] = ! empty( $input['read_h2_headings'] );
		$output['auto_generate'] = ! empty( $input['auto_generate'] );
		$public_types = get_post_types( array( 'public' => true ), 'names' );
		unset( $public_types['attachment'] );
		$output['post_types'] = array_values( array_intersect( array_map( 'sanitize_key', (array) ( $input['post_types'] ?? array() ) ), array_values( $public_types ) ) );
		$output['categories'] = array_values( array_unique( array_filter( array_map( 'absint', (array) ( $input['categories'] ?? array() ) ) ) ) );
		$preset = sanitize_key( (string) ( $input['player_preset'] ?? '' ) );
		$output['player_preset'] = in_array( $preset, array( 'light', 'dark' ), true ) ? $preset : (string) $existing['player_preset'];
		return $output;
	}

	/** @param array<string,mixed> $output @param array<string,mixed> $input */
	private function save_key( array &$output, array $input, string $key, string $clear_key, bool $defined ): void {
		if ( $defined || ! empty( $input[ $clear_key ] ) ) {
			$output[ $key ] = '';
		} elseif ( isset( $input[ $key ] ) && '' !== trim( (string) $input[ $key ] ) ) {
			$output[ $key ] = sanitize_text_field( trim( (string) $input[ $key ] ) );
		}
	}

	private static function normalise_admin_tab( ?string $requested_tab ): string {
		$active_tab = sanitize_key( (string) $requested_tab );
		$active_tab = 'cache' === $active_tab ? 'audio' : ( 'appearance' === $active_tab ? 'design' : $active_tab );
		return in_array( $active_tab, array( 'dashboard', 'narration', 'design', 'audio' ), true ) ? $active_tab : 'dashboard';
	}

	public function render_settings_page(): void {
		if ( ! current_user_can( 'manage_options' ) ) { return; }
		$settings = self::get_settings();
		$requested_tab = filter_input( INPUT_GET, 'tab', FILTER_UNSAFE_RAW );
		$active_tab = self::normalise_admin_tab( is_string( $requested_tab ) ? $requested_tab : null );
		?>
		<div class="wrap ai-narration-page">
			<h1 class="ai-narration-admin-brand" aria-label="<?php esc_attr_e( 'AI Narration', 'ai-narration' ); ?>"><strong aria-hidden="true">AI</strong><span aria-hidden="true">Narration</span></h1>
			<div class="ai-narration-admin">
				<p class="ai-narration-admin-intro"><?php esc_html_e( 'AI narration for selected pages, posts and other supported content.', 'ai-narration' ); ?></p>
				<p class="ai-narration-admin-storage-note"><?php esc_html_e( 'Completed narration is stored as content-addressed audio files in WordPress uploads and served directly to visitors.', 'ai-narration' ); ?></p>
				<div class="ai-narration-settings-errors"><?php settings_errors(); ?></div>
				<nav class="nav-tab-wrapper ai-narration-tabs" aria-label="<?php esc_attr_e( 'AI Narration sections', 'ai-narration' ); ?>">
					<button type="button" class="nav-tab<?php echo 'dashboard' === $active_tab ? ' nav-tab-active' : ''; ?>" data-ai-narration-tab="dashboard" aria-selected="<?php echo 'dashboard' === $active_tab ? 'true' : 'false'; ?>"><?php esc_html_e( 'Dashboard', 'ai-narration' ); ?></button>
					<button type="button" class="nav-tab<?php echo 'narration' === $active_tab ? ' nav-tab-active' : ''; ?>" data-ai-narration-tab="narration" aria-selected="<?php echo 'narration' === $active_tab ? 'true' : 'false'; ?>"><?php esc_html_e( 'Narration', 'ai-narration' ); ?></button>
					<button type="button" class="nav-tab<?php echo 'design' === $active_tab ? ' nav-tab-active' : ''; ?>" data-ai-narration-tab="design" aria-selected="<?php echo 'design' === $active_tab ? 'true' : 'false'; ?>"><?php esc_html_e( 'Appearance', 'ai-narration' ); ?></button>
					<button type="button" class="nav-tab<?php echo 'audio' === $active_tab ? ' nav-tab-active' : ''; ?>" data-ai-narration-tab="audio" aria-selected="<?php echo 'audio' === $active_tab ? 'true' : 'false'; ?>"><?php esc_html_e( 'Audio', 'ai-narration' ); ?></button>
					<a class="nav-tab ai-narration-get-pro-tab" href="https://www.getainarration.com/pro/" target="_blank" rel="noopener noreferrer" aria-label="<?php esc_attr_e( 'Get Pro (opens in a new tab)', 'ai-narration' ); ?>"><?php esc_html_e( 'Get Pro', 'ai-narration' ); ?></a>
				</nav>

				<div data-ai-narration-panel="dashboard"<?php echo 'dashboard' === $active_tab ? '' : ' hidden'; ?>><?php $this->render_dashboard(); ?></div>

				<form method="post" action="options.php" data-ai-narration-settings-form<?php echo in_array( $active_tab, array( 'narration', 'design' ), true ) ? '' : ' hidden'; ?>>
					<?php settings_fields( 'ai_narration_group' ); ?>
					<input type="hidden" name="ai_narration_settings[free_section]" value="combined">
					<div data-ai-narration-panel="narration"<?php echo 'narration' === $active_tab ? '' : ' hidden'; ?>>
						<?php $this->render_narration( $settings ); ?>
						<?php submit_button(); ?>
					</div>
					<div data-ai-narration-panel="design"<?php echo 'design' === $active_tab ? '' : ' hidden'; ?>>
						<?php $this->render_appearance( $settings ); ?>
						<?php submit_button(); ?>
					</div>
				</form>

				<div data-ai-narration-panel="audio"<?php echo 'audio' === $active_tab ? '' : ' hidden'; ?>><?php $this->render_cache(); ?></div>
			</div>
		</div>
		<?php
	}

	private function render_dashboard(): void {
		$articles = $this->cache->articles();
		$summary = $this->cache->summary( $articles );
		$settings = self::get_settings();
		?>
		<nav class="nav-tab-wrapper ai-narration-dashboard-tabs" aria-label="<?php esc_attr_e( 'Dashboard sections', 'ai-narration' ); ?>" role="tablist">
			<button type="button" class="nav-tab nav-tab-active" role="tab" aria-selected="true" data-ai-narration-dashboard-tab="status"><?php esc_html_e( 'Status', 'ai-narration' ); ?></button>
			<button type="button" class="nav-tab" role="tab" aria-selected="false" data-ai-narration-dashboard-tab="setup"><?php esc_html_e( 'Setup', 'ai-narration' ); ?></button>
		</nav>
		<div data-ai-narration-dashboard-panel="status">
		<div data-ai-narration-dashboard-status data-ai-narration-pending="<?php echo (int) ( (int) $summary['queued'] > 0 ); ?>">
			<?php $this->render_dashboard_status_card( $articles, $summary ); ?>
		</div>
		<section class="ai-narration-dashboard-card ai-narration-pro-card">
			<div class="ai-narration-pro-wordmark" role="img" aria-label="<?php esc_attr_e( 'AI Narration Pro', 'ai-narration' ); ?>"><span class="ai-narration-pro-wordmark-core" aria-hidden="true"><strong><?php esc_html_e( 'AI', 'ai-narration' ); ?></strong><span class="ai-narration-pro-wordmark-name"><?php esc_html_e( 'Narration', 'ai-narration' ); ?></span></span><small class="ai-narration-pro-wordmark-edition" aria-hidden="true"><?php esc_html_e( 'PRO', 'ai-narration' ); ?></small></div>
			<h3><?php esc_html_e( 'Unlock the full experience.', 'ai-narration' ); ?></h3>
			<p><?php esc_html_e( 'Add Gemini or ElevenLabs, manage audio in bulk, and unlock reusable Custom Audio, independent profiles, listening analytics and complete player customisation.', 'ai-narration' ); ?></p>
			<a class="button button-primary" href="https://www.getainarration.com/pro/" target="_blank" rel="noopener noreferrer"><?php esc_html_e( 'Explore AI Narration Pro', 'ai-narration' ); ?></a>
		</section>
		</div>
		<div data-ai-narration-dashboard-panel="setup" hidden>
			<?php $this->render_getting_started( $articles, $settings ); ?>
		</div>
		<?php
	}

	/**
	 * Render the Free onboarding checklist without duplicating settings.
	 *
	 * @param array<int,array<string,mixed>> $articles Eligible marked narration items.
	 * @param array<string,mixed>            $settings Current narration settings.
	 */
	private function render_getting_started( array $articles, array $settings ): void {
		$user_id = get_current_user_id();
		$credentials_complete = self::has_api_key();
		$selection_complete = $this->narration_selection_ready( $settings );
		$preview_complete = '1' === (string) get_user_meta( $user_id, self::GETTING_STARTED_PREVIEW_META_KEY, true );
		$marked_post_id = $this->first_marked_post_id( $articles );
		$generated_post_ids = array_values( array_map( 'absint', array_column( array_filter( $articles, static fn( array $article ): bool => ! empty( $article['has_active'] ) && ! empty( $article['audio_available'] ) ), 'post_id' ) ) );
		$generated_post_id = (int) ( $generated_post_ids[0] ?? 0 );
		$confirmed_post_id = absint( get_user_meta( $user_id, self::GETTING_STARTED_PLAYER_META_KEY, true ) );
		$player_complete = $confirmed_post_id > 0 && in_array( $confirmed_post_id, $generated_post_ids, true );
		$player_post_id = $player_complete ? $confirmed_post_id : $generated_post_id;
		$narration_url = self::settings_url( array( 'tab' => 'narration' ) );
		$audio_url = self::settings_url( array( 'tab' => 'audio' ) );
		$edit_url = $marked_post_id > 0 ? get_edit_post_link( $marked_post_id, 'raw' ) : false;
		$steps = array(
			array( 'label' => __( 'Add an OpenAI API key', 'ai-narration' ), 'description' => __( 'Connect the OpenAI credential used for narration.', 'ai-narration' ), 'complete' => $credentials_complete, 'url' => $narration_url . '#ai-narration-provider-credentials', 'action' => $credentials_complete ? __( 'Review', 'ai-narration' ) : __( 'Add key', 'ai-narration' ) ),
			array( 'label' => __( 'Select a model and voice', 'ai-narration' ), 'description' => __( 'Choose the settings used for page narration.', 'ai-narration' ), 'complete' => $selection_complete, 'url' => $narration_url . '#ai-narration-provider', 'action' => $selection_complete ? __( 'Review', 'ai-narration' ) : __( 'Choose settings', 'ai-narration' ) ),
			array( 'label' => __( 'Preview the selected voice', 'ai-narration' ), 'description' => __( 'Hear a short sample before generating narration.', 'ai-narration' ), 'complete' => $preview_complete, 'url' => $narration_url . '#ai-narration-preview-voice', 'action' => $preview_complete ? __( 'Preview again', 'ai-narration' ) : __( 'Preview voice', 'ai-narration' ) ),
			array( 'label' => __( 'Add a placement shortcode or HTML marker', 'ai-narration' ), 'description' => __( 'Choose where the public player appears in your content.', 'ai-narration' ), 'complete' => $marked_post_id > 0, 'url' => $narration_url . '#ai-narration-marker-guide', 'action' => $marked_post_id > 0 ? __( 'Review', 'ai-narration' ) : __( 'View placement', 'ai-narration' ) ),
			array( 'label' => __( 'Enable narration and generate the first item', 'ai-narration' ), 'description' => __( 'Create the first complete stored narration.', 'ai-narration' ), 'complete' => $generated_post_id > 0, 'url' => $generated_post_id > 0 ? $audio_url : ( $edit_url ?: $audio_url ), 'action' => $generated_post_id > 0 ? __( 'Open Audio', 'ai-narration' ) : ( $edit_url ? __( 'Open content', 'ai-narration' ) : __( 'Open Audio', 'ai-narration' ) ) ),
			array( 'label' => __( 'Confirm the public player', 'ai-narration' ), 'description' => __( 'Open the generated page and check playback as a visitor.', 'ai-narration' ), 'complete' => $player_complete, 'url' => $player_complete && $player_post_id > 0 ? get_permalink( $player_post_id ) : '', 'action' => $player_complete ? __( 'View player', 'ai-narration' ) : __( 'Check player', 'ai-narration' ), 'confirm_id' => ! $player_complete ? $player_post_id : 0 ),
		);
		?>
		<section class="ai-narration-getting-started" aria-labelledby="ai-narration-getting-started-title">
			<header class="ai-narration-getting-started__header">
				<h3 id="ai-narration-getting-started-title"><?php esc_html_e( 'Getting started', 'ai-narration' ); ?></h3>
				<p><?php esc_html_e( 'Work through the established setup path. Each item opens the existing setting or task.', 'ai-narration' ); ?></p>
			</header>
			<ol class="ai-narration-getting-started__steps">
				<?php foreach ( $steps as $index => $step ) : ?>
					<li class="ai-narration-getting-started__step<?php echo ! empty( $step['complete'] ) ? ' is-complete' : ''; ?>">
						<span class="ai-narration-getting-started__marker" aria-hidden="true"><?php echo ! empty( $step['complete'] ) ? '&#10003;' : ''; ?></span>
						<span class="screen-reader-text"><?php echo esc_html( ! empty( $step['complete'] ) ? __( 'Complete', 'ai-narration' ) : __( 'Not complete', 'ai-narration' ) ); ?></span>
						<div class="ai-narration-getting-started__copy"><strong><?php echo esc_html( (string) $step['label'] ); ?></strong><span><?php echo esc_html( (string) $step['description'] ); ?></span></div>
						<?php if ( ! empty( $step['confirm_id'] ) ) : ?>
							<form method="post" target="_blank" rel="noopener" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>"><input type="hidden" name="action" value="ai_narration_confirm_public_player"><input type="hidden" name="post_id" value="<?php echo esc_attr( (string) $step['confirm_id'] ); ?>"><?php wp_nonce_field( 'ai_narration_confirm_public_player' ); ?><button type="submit" class="button button-secondary"><?php echo esc_html( (string) $step['action'] ); ?></button></form>
						<?php elseif ( ! empty( $step['url'] ) ) : ?>
							<a class="button button-secondary" href="<?php echo esc_url( (string) $step['url'] ); ?>"<?php echo ! empty( $step['complete'] ) && 5 === $index ? ' target="_blank" rel="noopener noreferrer"' : ''; ?>><?php echo esc_html( (string) $step['action'] ); ?></a>
						<?php else : ?><span class="ai-narration-getting-started__waiting"><?php esc_html_e( 'Generate audio first', 'ai-narration' ); ?></span><?php endif; ?>
					</li>
				<?php endforeach; ?>
			</ol>
		</section>
		<?php
	}

	/** @param array<string,mixed> $settings Current narration settings. */
	private function narration_selection_ready( array $settings ): bool {
		return self::has_narration_credentials() && array_key_exists( (string) ( $settings['model'] ?? '' ), self::models() ) && array_key_exists( (string) ( $settings['voice'] ?? '' ), self::voices() );
	}

	/** @param array<int,array<string,mixed>> $articles Eligible marked narration items. */
	private function first_marked_post_id( array $articles ): int {
		$known_post_id = absint( $articles[0]['post_id'] ?? 0 );
		if ( $known_post_id > 0 ) { return $known_post_id; }
		$post_types = get_post_types( array( 'public' => true ), 'names' );
		unset( $post_types['attachment'] );
		$post_ids = get_posts( array( 'post_type' => array_values( $post_types ), 'post_status' => 'publish', 'posts_per_page' => -1, 'fields' => 'ids', 'orderby' => 'modified', 'order' => 'DESC', 'no_found_rows' => true ) );
		foreach ( $post_ids as $post_id ) {
			$post_id = absint( $post_id );
			if ( $post_id > 0 && $this->content->has_narration_marker( $post_id ) ) { return $post_id; }
		}
		return 0;
	}

	/** Mark the generated public player as checked, then open that content. */
	public function confirm_public_player(): void {
		if ( ! current_user_can( 'manage_options' ) || ! check_admin_referer( 'ai_narration_confirm_public_player' ) ) { wp_die( esc_html__( 'You cannot confirm this player.', 'ai-narration' ) ); }
		$post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;
		$permalink = $post_id > 0 ? get_permalink( $post_id ) : false;
		if ( $post_id < 1 || ! $permalink || ! $this->content->has_narration_marker( $post_id ) || null === $this->cache->get_playable_manifest( $post_id ) ) { wp_safe_redirect( self::settings_url() ); exit; }
		update_user_meta( get_current_user_id(), self::GETTING_STARTED_PLAYER_META_KEY, $post_id );
		wp_safe_redirect( $permalink );
		exit;
	}

	/**
	 * @param array<int,array<string,mixed>> $articles Eligible narration rows.
	 * @param array<string,int>              $summary  Cache summary.
	 */
	private function render_dashboard_status_card( array $articles, array $summary ): void {
		$processing = (int) $summary['queued'] > 0;
		$failed = (int) $summary['failed'];
		$queue_delayed = $this->dashboard_queue_delayed( $articles );
		$label = $failed > 0 ? __( 'Needs attention', 'ai-narration' ) : ( $processing ? __( 'Processing', 'ai-narration' ) : __( 'Ready', 'ai-narration' ) );
		$modifier = $failed > 0 ? 'failed' : ( $processing ? 'queued' : 'ready' );
		$health = AI_Narration_Background::health();
		$heartbeat = absint( $health['last_heartbeat'] ?? 0 );
		?>
		<section class="ai-narration-dashboard-card">
			<span class="ai-narration-cache-status ai-narration-cache-status--<?php echo esc_attr( $modifier ); ?>"><?php echo esc_html( $label ); ?></span>
			<h3><?php echo esc_html( $failed > 0 ? __( 'AI Narration needs attention.', 'ai-narration' ) : ( $processing ? __( 'AI Narration is processing audio.', 'ai-narration' ) : __( 'Narration is ready.', 'ai-narration' ) ) ); ?></h3>
			<?php /* translators: 1: ready count, 2: previous-settings count, 3: queued count, 4: failed count, 5: not-generated count. */ ?>
			<p><?php echo esc_html( sprintf( __( '%1$d ready, %2$d using previous settings, %3$d queued, %4$d failed and %5$d not generated.', 'ai-narration' ), $summary['ready'], $summary['previous'], $summary['queued'], $summary['failed'], $summary['missing'] ) ); ?></p>
			<?php /* translators: %s: human-readable time since the background runner last checked in. */ ?>
			<p><strong><?php esc_html_e( 'Background processing:', 'ai-narration' ); ?></strong> <?php echo esc_html( $heartbeat ? sprintf( __( 'The scheduled runner checked in %s ago.', 'ai-narration' ), human_time_diff( $heartbeat, time() ) ) : __( 'Waiting for the scheduled runner’s first check-in.', 'ai-narration' ) ); ?></p>
			<details class="ai-narration-background-details"><summary><?php esc_html_e( 'Background processing details', 'ai-narration' ); ?></summary>
				<div class="ai-narration-background-details__body">
				<p><?php echo esc_html( AI_Narration_Background::fallback_scheduled() ? __( 'The WordPress scheduling fallback is active.', 'ai-narration' ) : __( 'The scheduling fallback will be restored on the next request.', 'ai-narration' ) ); ?></p>
				<?php if ( $queue_delayed || $failed > 0 ) : ?>
					<div class="ai-narration-background-actions">
						<?php if ( $queue_delayed ) : ?><form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>"><input type="hidden" name="action" value="ai_narration_run_queue_now"><?php wp_nonce_field( 'ai_narration_run_queue_now' ); ?><button class="button" type="submit"><?php esc_html_e( 'Run queue now', 'ai-narration' ); ?></button></form><?php endif; ?>
						<?php if ( $failed > 0 ) : ?><form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>"><input type="hidden" name="action" value="ai_narration_retry_failed"><?php wp_nonce_field( 'ai_narration_retry_failed' ); ?><button class="button" type="submit"><?php esc_html_e( 'Retry failed', 'ai-narration' ); ?></button></form><?php endif; ?>
					</div>
				<?php endif; ?>
				</div>
			</details>
		</section>
		<?php
	}

	/** @param array<int,array<string,mixed>> $articles Eligible narration rows. */
	private function dashboard_queue_delayed( array $articles ): bool {
		$now = time();
		$delayed_candidate = false;
		foreach ( $articles as $article ) {
			$status = sanitize_key( (string) ( $article['status'] ?? '' ) );
			if ( ! in_array( $status, array( 'queued', 'generating', 'regenerating', 'retrying' ), true ) ) {
				continue;
			}
			$updated = absint( $article['updated'] ?? 0 );
			$retry_due = 'retrying' !== $status || absint( $article['next_attempt'] ?? 0 ) <= $now;
			if ( $updated > 0 && $updated <= $now - ( 3 * MINUTE_IN_SECONDS ) && $retry_due ) {
				$delayed_candidate = true;
				break;
			}
		}

		if ( ! $delayed_candidate ) {
			return false;
		}

		$health = AI_Narration_Background::health();
		$worker_activity = absint( $health['last_worker_activity'] ?? 0 );
		return ! $this->has_active_worker_lock()
			&& ( 0 === $worker_activity || $worker_activity <= $now - ( 3 * MINUTE_IN_SECONDS ) );
	}

	private function has_active_worker_lock(): bool {
		global $wpdb;
		// A wildcard query is required to enumerate the plugin's expiring lock options; each option value is then read through get_option().
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
		$lock_names = $wpdb->get_col(
			$wpdb->prepare(
				"SELECT option_name FROM {$wpdb->options} WHERE option_name LIKE %s",
				$wpdb->esc_like( 'ai_narration_worker_lock_' ) . '%'
			)
		);
		$now = time();
		foreach ( $lock_names as $lock_name ) {
			$lease = get_option( (string) $lock_name, false );
			if ( is_array( $lease ) && absint( $lease['expires'] ?? 0 ) > $now ) {
				return true;
			}
		}
		return false;
	}

	/** @param array<string,mixed> $settings */
	private function render_narration( array $settings ): void {
		$post_types = get_post_types( array( 'public' => true, 'show_ui' => true ), 'objects' ); unset( $post_types['attachment'] );
		$categories = get_categories( array( 'hide_empty' => false ) );
		?>
		<h2><?php esc_html_e( 'Narration', 'ai-narration' ); ?></h2>
		<p><?php esc_html_e( 'Choose an OpenAI model and voice for narration. Existing stored audio remains available until you deliberately regenerate it.', 'ai-narration' ); ?></p>
		<?php $this->render_pro_context( __( 'Free uses OpenAI with one narration profile. Gemini, ElevenLabs and additional narration profiles are available with', 'ai-narration' ) ); ?>
		<h3 id="ai-narration-provider-credentials"><?php esc_html_e( 'Provider credentials', 'ai-narration' ); ?></h3>
		<table class="form-table" role="presentation"><?php $this->render_key_row( 'api_key', 'clear_api_key', __( 'OpenAI API key', 'ai-narration' ), self::has_api_key(), defined( 'AI_NARRATION_OPENAI_API_KEY' ) ); ?></table>
		<hr class="ai-narration-settings-divider">
		<h3 id="ai-narration-provider"><?php esc_html_e( 'Voice and delivery', 'ai-narration' ); ?></h3>
		<table class="form-table" role="presentation">
			<?php $this->render_provider_rows( $settings, 'openai' ); ?>
			<tr><th><?php esc_html_e( 'Heading narration', 'ai-narration' ); ?></th><td><label><input type="checkbox" name="ai_narration_settings[read_h2_headings]" value="1" <?php checked( ! empty( $settings['read_h2_headings'] ) ); ?>> <?php esc_html_e( 'Include H2 headings in narration', 'ai-narration' ); ?></label></td></tr>
		</table>
		<hr class="ai-narration-settings-divider">
		<h3 id="ai-narration-marker-guide"><?php esc_html_e( 'Narration placement', 'ai-narration' ); ?></h3>
		<p><?php esc_html_e( 'Add the start shortcode where the player should appear and narration should begin. Add the recommended stop shortcode where narration should end. Without it, narration continues through the remaining supported page content.', 'ai-narration' ); ?></p>
		<div class="ai-narration-shortcodes"><?php $this->render_shortcode( 'ai-narration-start', __( 'Start shortcode', 'ai-narration' ), '[ai_narration]' ); ?><?php $this->render_shortcode( 'ai-narration-stop', __( 'Recommended stop shortcode', 'ai-narration' ), '[ai_narration_stop]' ); ?></div>
		<details class="ai-narration-advanced-markers">
			<summary><?php esc_html_e( 'Advanced HTML markers', 'ai-narration' ); ?></summary>
			<p><?php esc_html_e( 'HTML markers remain invisible while AI Narration is inactive. Unprocessed shortcodes may appear as text.', 'ai-narration' ); ?></p>
			<p><code>&lt;div data-narration-start&gt;&lt;/div&gt;</code> <code>&lt;div data-narration-stop&gt;&lt;/div&gt;</code></p>
		</details>
		<h3><?php esc_html_e( 'Eligibility and generation', 'ai-narration' ); ?></h3><p><?php esc_html_e( 'Leave every post type unchecked to use only individual content overrides.', 'ai-narration' ); ?></p>
		<table class="form-table" role="presentation"><tr><th><?php esc_html_e( 'Automatic generation', 'ai-narration' ); ?></th><td><label><input type="checkbox" name="ai_narration_settings[auto_generate]" value="1" <?php checked( ! empty( $settings['auto_generate'] ) ); ?>> <?php esc_html_e( 'Generate narration when eligible narrated content is published or updated', 'ai-narration' ); ?></label><p class="description"><?php esc_html_e( 'When disabled, use Generate or Regenerate from the Audio tab.', 'ai-narration' ); ?></p></td></tr><tr><th><?php esc_html_e( 'Post types', 'ai-narration' ); ?></th><td><?php foreach ( $post_types as $post_type ) : ?><label class="ai-narration-block-option"><input type="checkbox" name="ai_narration_settings[post_types][]" value="<?php echo esc_attr( $post_type->name ); ?>" <?php checked( in_array( $post_type->name, (array) $settings['post_types'], true ) ); ?>> <?php echo esc_html( $post_type->labels->singular_name ); ?></label><?php endforeach; ?></td></tr><tr><th><?php esc_html_e( 'Categories', 'ai-narration' ); ?></th><td><?php if ( empty( $categories ) ) : ?><p><?php esc_html_e( 'No categories found.', 'ai-narration' ); ?></p><?php else : foreach ( $categories as $category ) : ?><label class="ai-narration-block-option"><input type="checkbox" name="ai_narration_settings[categories][]" value="<?php echo esc_attr( (string) $category->term_id ); ?>" <?php checked( in_array( (int) $category->term_id, array_map( 'intval', (array) $settings['categories'] ), true ) ); ?>> <?php echo esc_html( $category->name ); ?></label><?php endforeach; endif; ?></td></tr></table>
		<?php
	}

	private function render_key_row( string $key, string $clear, string $label, bool $saved, bool $defined ): void {
		?><tr><th><label for="ai-narration-<?php echo esc_attr( $key ); ?>"><?php echo esc_html( $label ); ?></label></th><td><input id="ai-narration-<?php echo esc_attr( $key ); ?>" class="regular-text" type="password" autocomplete="new-password" name="ai_narration_settings[<?php echo esc_attr( $key ); ?>]" value="" <?php disabled( $defined ); ?> placeholder="<?php echo esc_attr( $saved ? __( 'Saved — enter a replacement', 'ai-narration' ) : __( 'Enter API key', 'ai-narration' ) ); ?>"><?php if ( $defined ) : ?><p class="description"><?php esc_html_e( 'Defined in wp-config.php.', 'ai-narration' ); ?></p><?php elseif ( $saved ) : ?><label class="ai-narration-remove-key"><input type="checkbox" name="ai_narration_settings[<?php echo esc_attr( $clear ); ?>]" value="1"> <?php esc_html_e( 'Remove the saved key', 'ai-narration' ); ?></label><?php endif; ?></td></tr><?php
	}

	/** @param array<string,mixed> $settings */
	private function render_provider_rows( array $settings, string $provider ): void {
		unset( $provider );
		$models = self::models();
		$voices = self::voices();
		?>
		<tr><th><label for="ai-narration-model"><?php esc_html_e( 'Speech model', 'ai-narration' ); ?></label></th><td><select id="ai-narration-model" name="ai_narration_settings[model]"><?php foreach ( $models as $id => $label ) : ?><option value="<?php echo esc_attr( $id ); ?>" <?php selected( $settings['model'], $id ); ?>><?php echo esc_html( $label ); ?></option><?php endforeach; ?></select></td></tr>
		<tr><th><label for="ai-narration-voice"><?php esc_html_e( 'Voice', 'ai-narration' ); ?></label></th><td><select id="ai-narration-voice" name="ai_narration_settings[voice]"><?php foreach ( $voices as $id => $label ) : ?><option value="<?php echo esc_attr( $id ); ?>" <?php selected( $settings['voice'], $id ); ?>><?php echo esc_html( $label ); ?></option><?php endforeach; ?></select><div id="ai-narration-preview-voice" class="ai-narration-voice-preview"><button type="button" class="button" data-ai-narration-preview data-provider="openai"><?php esc_html_e( 'Preview selected voice', 'ai-narration' ); ?></button><span data-ai-narration-preview-status role="status"></span></div></td></tr>
		<tr><th><label for="ai-narration-instructions"><?php esc_html_e( 'Narration instructions', 'ai-narration' ); ?></label></th><td><textarea id="ai-narration-instructions" class="large-text" rows="5" name="ai_narration_settings[instructions]"><?php echo esc_textarea( (string) $settings['instructions'] ); ?></textarea></td></tr>
		<?php
	}

	private function render_shortcode( string $id, string $label, string $value ): void {
		?><div class="ai-narration-marker-row"><label for="<?php echo esc_attr( $id ); ?>"><strong><?php echo esc_html( $label ); ?></strong></label><div class="ai-narration-marker-copy"><input id="<?php echo esc_attr( $id ); ?>" class="regular-text code ai-narration-marker-code" type="text" readonly value="<?php echo esc_attr( $value ); ?>"><button type="button" class="button button-secondary" data-ai-narration-copy="<?php echo esc_attr( $id ); ?>"><?php esc_html_e( 'Copy', 'ai-narration' ); ?></button></div></div><?php
	}

	/** @param array<string,mixed> $settings */
	private function render_appearance( array $settings ): void {
		$presets = array(
			'light'     => array( __( 'Light', 'ai-narration' ), __( 'Uses a restrained light player surface.', 'ai-narration' ) ),
			'dark'      => array( __( 'Dark', 'ai-narration' ), __( 'Uses the AI Narration dark player surface.', 'ai-narration' ) ),
		);
		?>
		<h2><?php esc_html_e( 'Appearance', 'ai-narration' ); ?></h2>
		<p><?php esc_html_e( 'Choose a Light or Dark player preset. Both include the estimated listening time and the same moderate corner radius.', 'ai-narration' ); ?></p>
		<?php $this->render_pro_context( __( 'Free includes fixed Light and Dark presets. Custom colours, corner radius, plus additional options and controls are available with', 'ai-narration' ) ); ?>
		<div class="ai-narration-design-layout ai-narration-free-design-layout">
			<div class="ai-narration-design-controls">
				<h3><?php esc_html_e( 'Player preset', 'ai-narration' ); ?></h3>
				<div class="ai-narration-theme-options" data-ai-narration-player-presets>
					<?php foreach ( $presets as $id => $details ) : ?>
						<input class="screen-reader-text" id="ai-narration-player-preset-<?php echo esc_attr( $id ); ?>" type="radio" name="ai_narration_settings[player_preset]" value="<?php echo esc_attr( $id ); ?>" <?php checked( $settings['player_preset'], $id ); ?>>
						<button type="button" class="button ai-narration-theme-option" data-ai-narration-player-preset="<?php echo esc_attr( $id ); ?>" aria-pressed="<?php echo $settings['player_preset'] === $id ? 'true' : 'false'; ?>"><?php echo esc_html( $details[0] ); ?></button>
					<?php endforeach; ?>
				</div>
				<p class="description" data-ai-narration-preset-description><?php echo esc_html( $presets[ $settings['player_preset'] ][1] ); ?></p>
			</div>

			<div class="ai-narration-design-preview-wrap">
				<h3><?php esc_html_e( 'Player preview', 'ai-narration' ); ?></h3>
				<p class="description"><?php esc_html_e( 'Shows the selected player preset and its playback state.', 'ai-narration' ); ?></p>
				<div class="ai-narration-design-preview" data-ai-narration-preview-surface>
					<section class="ai-narration ai-narration--admin-preview has-idle-duration" data-ai-narration-preview-mode="default" data-ai-narration-player-preview aria-label="<?php esc_attr_e( 'AI Narration — AI-generated voice preview', 'ai-narration' ); ?>">
						<div class="ai-narration__controls">
							<button class="ai-narration__play" type="button" aria-label="<?php esc_attr_e( 'Play', 'ai-narration' ); ?>">
								<svg class="ai-narration__icon ai-narration__icon--play" viewBox="0 0 24 24" aria-hidden="true"><path d="M5.5 3.5v17L20 12z"/></svg>
								<svg class="ai-narration__icon ai-narration__icon--pause" viewBox="0 0 24 24" aria-hidden="true"><path d="M5.5 3.5h5v17h-5zm8 0h5v17h-5z"/></svg>
								<span class="screen-reader-text"><?php esc_html_e( 'Play', 'ai-narration' ); ?></span>
							</button>
							<div class="ai-narration__timeline is-idle">
								<span class="ai-narration__title"><?php esc_html_e( 'Listen', 'ai-narration' ); ?></span>
								<span class="ai-narration__idle-meta"><span class="ai-narration__idle-divider" aria-hidden="true"></span><span class="ai-narration__idle-duration" aria-hidden="true"><?php esc_html_e( '~5:00', 'ai-narration' ); ?></span><span class="screen-reader-text"><?php esc_html_e( 'Estimated listening time: approximately 5 minutes.', 'ai-narration' ); ?></span></span>
								<div class="ai-narration__status" role="status" aria-live="polite"></div>
								<div class="ai-narration__transport">
									<div class="ai-narration__time" aria-hidden="true"><span class="ai-narration__duration"><?php esc_html_e( '~5:00', 'ai-narration' ); ?></span></div>
									<span class="ai-narration__transport-divider" aria-hidden="true"></span>
									<div class="ai-narration__skip-group">
										<button class="ai-narration__skip ai-narration__skip--back" type="button" aria-label="<?php esc_attr_e( 'Rewind 15 seconds', 'ai-narration' ); ?>" disabled><svg class="ai-narration__skip-icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M9 4v12L1.5 10 9 4Zm9 0v12l-7.5-6L18 4Z"/></svg></button>
										<span class="ai-narration__skip-divider" aria-hidden="true"></span>
										<button class="ai-narration__skip ai-narration__skip--forward" type="button" aria-label="<?php esc_attr_e( 'Forward 15 seconds', 'ai-narration' ); ?>" disabled><svg class="ai-narration__skip-icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M9 4v12L1.5 10 9 4Zm9 0v12l-7.5-6L18 4Z"/></svg></button>
									</div>
								</div>
							</div>
							<span class="ai-narration__disclosure"><?php echo esc_html( self::player_disclosure() ); ?></span>
						</div>
					</section>
				</div>
			</div>
		</div>
		<?php
	}

	private function render_cache(): void {
		// These values only filter and paginate this read-only administration view.
		// phpcs:disable WordPress.Security.NonceVerification.Recommended
		$search = sanitize_text_field( (string) ( isset( $_GET['s'] ) ? wp_unslash( $_GET['s'] ) : '' ) );
		$view = $this->cache_view( $search, absint( $_GET['paged'] ?? 1 ) );
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
		$summary = $view['summary']; $filtered = $view['filtered']; $page = $view['page']; $pages = $view['pages']; $rows = $view['rows'];
		?><h2><?php esc_html_e( 'Audio cache', 'ai-narration' ); ?></h2><p><?php esc_html_e( 'OpenAI narration is generated in the background. Existing stored audio remains playable while its verified replacement is prepared.', 'ai-narration' ); ?></p><?php $this->render_pro_context( __( 'Free provides individual search, playback and regeneration. Bulk management, advanced filters and reusable Custom Audio are available with', 'ai-narration' ) ); ?><div class="ai-narration-cache-summary" data-ai-narration-cache-summary data-ai-narration-pending="<?php echo (int) ( (int) $summary['queued'] > 0 ); ?>"><?php $this->render_cache_summary_items( $summary ); ?></div>
		<form class="ai-narration-cache-toolbar ai-narration-cache-toolbar--search-only" method="get"><input type="hidden" name="page" value="ai-narration"><input type="hidden" name="tab" value="cache"><input class="ai-narration-cache-search" type="search" name="s" value="<?php echo esc_attr( $search ); ?>" placeholder="<?php esc_attr_e( 'Search content or ID…', 'ai-narration' ); ?>" aria-label="<?php esc_attr_e( 'Search content or ID', 'ai-narration' ); ?>"></form>
		<div id="ai-narration-cache-audition" class="ai-narration-cache-audition" data-ai-narration-cache-audition role="region" aria-label="<?php esc_attr_e( 'Cached narration audition player', 'ai-narration' ); ?>" hidden>
			<div class="ai-narration-cache-audition-title"><span><?php esc_html_e( 'Now previewing', 'ai-narration' ); ?></span><strong data-ai-narration-cache-audition-title></strong></div>
			<div class="ai-narration-cache-audition-controls">
				<button type="button" class="button" data-ai-narration-cache-restart><?php esc_html_e( 'Restart', 'ai-narration' ); ?></button>
				<button type="button" class="button ai-narration-cache-skip" data-ai-narration-cache-skip="-15" aria-label="<?php esc_attr_e( 'Rewind 15 seconds', 'ai-narration' ); ?>">−15</button>
				<button type="button" class="button button-primary ai-narration-cache-audition-play" data-ai-narration-cache-audition-play aria-label="<?php esc_attr_e( 'Play cached narration', 'ai-narration' ); ?>" aria-pressed="false"><?php esc_html_e( 'Play', 'ai-narration' ); ?></button>
				<button type="button" class="button ai-narration-cache-skip" data-ai-narration-cache-skip="15" aria-label="<?php esc_attr_e( 'Forward 15 seconds', 'ai-narration' ); ?>">+15</button>
				<span class="ai-narration-cache-audition-time" data-ai-narration-cache-current-time>0:00</span>
				<input class="ai-narration-cache-audition-range" type="range" min="0" max="0" value="0" step="0.1" aria-label="<?php esc_attr_e( 'Seek through cached narration', 'ai-narration' ); ?>" data-ai-narration-cache-seek disabled>
				<span class="ai-narration-cache-audition-time" data-ai-narration-cache-total-time>—:——</span>
				<button type="button" class="button-link ai-narration-cache-audition-close" data-ai-narration-cache-audition-close aria-label="<?php esc_attr_e( 'Close cached narration player', 'ai-narration' ); ?>"><?php esc_html_e( 'Close', 'ai-narration' ); ?></button>
			</div>
			<p class="ai-narration-cache-audition-status" data-ai-narration-cache-audition-status aria-live="polite" hidden></p>
		</div>
		<div class="ai-narration-cache-table-wrap"><table class="widefat striped ai-narration-cache-table ai-narration-free-cache-table"><thead><tr><th><?php esc_html_e( 'Content', 'ai-narration' ); ?></th><th><?php esc_html_e( 'Status', 'ai-narration' ); ?></th><th><?php esc_html_e( 'Generated', 'ai-narration' ); ?></th><th><?php esc_html_e( 'Audio', 'ai-narration' ); ?></th><th><?php esc_html_e( 'Voice and model', 'ai-narration' ); ?></th><th><?php esc_html_e( 'Actions', 'ai-narration' ); ?></th></tr></thead><tbody data-ai-narration-cache-body><?php $this->render_cache_rows( $rows, $search ); ?></tbody></table></div>
		<?php /* translators: 1: current page number, 2: total page count. */ ?>
		<?php if ( count( $filtered ) > 0 ) : ?><div class="ai-narration-cache-profile-footer"><p class="description ai-narration-cache-footnote"><?php esc_html_e( 'Regenerate creates and verifies a replacement beside the current audio, then swaps it in atomically.', 'ai-narration' ); ?></p><div class="ai-narration-pagination"><span><?php echo esc_html( sprintf( '%1$d–%2$d of %3$d', ( $page - 1 ) * self::PAGE_SIZE + 1, min( $page * self::PAGE_SIZE, count( $filtered ) ), count( $filtered ) ) ); ?></span><?php if ( $page > 1 ) : ?><a class="button" href="<?php echo esc_url( add_query_arg( 'paged', $page - 1 ) ); ?>"><?php esc_html_e( 'Previous', 'ai-narration' ); ?></a><?php endif; ?><span><?php echo esc_html( sprintf( __( 'Page %1$d of %2$d', 'ai-narration' ), $page, $pages ) ); ?></span><?php if ( $page < $pages ) : ?><a class="button" href="<?php echo esc_url( add_query_arg( 'paged', $page + 1 ) ); ?>"><?php esc_html_e( 'Next', 'ai-narration' ); ?></a><?php endif; ?></div></div><?php endif; ?>
		<?php
	}

	/** @return array{summary:array<string,int>,filtered:array<int,array<string,mixed>>,page:int,pages:int,rows:array<int,array<string,mixed>>} */
	private function cache_view( string $search, int $requested_page ): array {
		$articles = $this->cache->articles();
		$summary = $this->cache->summary( $articles );
		$filtered = array_values( array_filter( $articles, static function ( array $item ) use ( $search ): bool { return '' === $search || false !== stripos( (string) $item['title'] . ' ' . (string) $item['post_id'], $search ); } ) );
		$pages = max( 1, (int) ceil( count( $filtered ) / self::PAGE_SIZE ) );
		$page = min( max( 1, $requested_page ), $pages );
		return array( 'summary' => $summary, 'filtered' => $filtered, 'page' => $page, 'pages' => $pages, 'rows' => array_slice( $filtered, ( $page - 1 ) * self::PAGE_SIZE, self::PAGE_SIZE ) );
	}

	/** @param array<string,int> $summary */
	private function render_cache_summary_items( array $summary ): void {
		?><span><strong><?php echo esc_html( (string) $summary['ready'] ); ?></strong> ready</span><span><strong><?php echo esc_html( (string) $summary['previous'] ); ?></strong> previous audio</span><span><strong><?php echo esc_html( (string) $summary['queued'] ); ?></strong> queued</span><span><strong><?php echo esc_html( (string) $summary['failed'] ); ?></strong> failed</span><span><strong><?php echo esc_html( size_format( $summary['bytes'], 1 ) ); ?></strong> stored</span><?php
	}

	/** @param array<int,array<string,mixed>> $rows */
	private function render_cache_rows( array $rows, string $search ): void {
		if ( empty( $rows ) ) {
			?><tr><td colspan="6"><?php echo esc_html( '' === $search ? __( 'No narration content is available.', 'ai-narration' ) : __( 'No content matches the current search.', 'ai-narration' ) ); ?></td></tr><?php
			return;
		}
		foreach ( $rows as $index => $row ) { $this->render_cache_row( $row, (int) $index ); }
	}

	public function free_status(): void {
		$this->require_admin( __( 'You are not allowed to view AI Narration status.', 'ai-narration' ) );
		check_ajax_referer( 'ai_narration_free_status', 'nonce' );
		$search = sanitize_text_field( (string) ( isset( $_POST['search'] ) ? wp_unslash( $_POST['search'] ) : '' ) );
		$view = $this->cache_view( $search, absint( $_POST['page'] ?? 1 ) );
		if ( (int) $view['summary']['queued'] > 0 ) {
			// Status polling also reasserts a prompt wake-up. This is a safe
			// self-heal when a host accepts but drops a non-blocking loopback.
			$this->cache->run_due_queue_now();
		}
		ob_start(); $this->render_dashboard_status_card( $this->cache->articles(), $view['summary'] ); $dashboard_html = (string) ob_get_clean();
		ob_start(); $this->render_cache_summary_items( $view['summary'] ); $summary_html = (string) ob_get_clean();
		ob_start(); $this->render_cache_rows( $view['rows'], $search ); $rows_html = (string) ob_get_clean();
		wp_send_json_success( array( 'dashboardHtml' => $dashboard_html, 'summaryHtml' => $summary_html, 'rowsHtml' => $rows_html, 'hasPending' => (int) $view['summary']['queued'] > 0 ) );
	}

	private function render_pro_context( string $text ): void {
		?><p class="description ai-narration-pro-context"><?php echo esc_html( $text ); ?> <a href="https://www.getainarration.com/pro/" target="_blank" rel="noopener noreferrer"><?php esc_html_e( 'AI Narration Pro', 'ai-narration' ); ?></a>.</p><?php
	}

	/** @param array<string,mixed> $row */
	private function cache_row_signature( array $row ): string {
		$fields = array( 'status', 'audio_available', 'created', 'bytes', 'chunks', 'voice', 'model', 'provider', 'urls', 'error', 'updated', 'completed', 'total', 'next_attempt' );
		$signature = array();
		foreach ( $fields as $field ) {
			$signature[ $field ] = $row[ $field ] ?? null;
		}
		return hash( 'sha256', (string) wp_json_encode( $signature ) );
	}

	/** @param array<string,mixed> $row */
	private function render_cache_row( array $row, int $row_index ): void {
		$id = absint( $row['post_id'] ); $title = (string) $row['title']; $state = sanitize_key( (string) $row['status'] );
		$row_class = 0 === $row_index % 2 ? ' ai-narration-cache-row--alternate' : '';
		$labels = array( 'ready' => 'Ready', 'previous' => 'Previous audio', 'queued' => 'Queued', 'generating' => 'Generating', 'regenerating' => 'Regenerating', 'retrying' => 'Retrying', 'failed' => ! empty( $row['audio_available'] ) ? 'Replacement failed' : 'Failed', 'missing' => 'Not generated' );
		/* translators: 1: number of audio chunks, 2: formatted audio file size. */
		$generated = ! empty( $row['created'] ) ? wp_date( 'j F Y, ' . get_option( 'time_format' ), (int) $row['created'] ) : '—'; $audio = ! empty( $row['audio_available'] ) ? sprintf( _n( '%1$d chunk · %2$s', '%1$d chunks · %2$s', (int) $row['chunks'], 'ai-narration' ), $row['chunks'], size_format( $row['bytes'], 1 ) ) : '—';
		$provider = sanitize_key( (string) $row['provider'] ); $provider_label = 'openai' === $provider ? 'OpenAI' : __( 'Existing audio', 'ai-narration' ); $urls = ! empty( $row['urls'] ) ? array_values( array_map( 'esc_url_raw', (array) $row['urls'] ) ) : array();
		$generate_label = 'failed' === $state ? __( 'Retry', 'ai-narration' ) : ( ! empty( $row['audio_available'] ) ? __( 'Regenerate', 'ai-narration' ) : __( 'Generate', 'ai-narration' ) );
		/* translators: %s: content title. */
		?><tr class="ai-narration-cache-row<?php echo esc_attr( $row_class ); ?>" data-ai-narration-cache-row data-post-id="<?php echo esc_attr( (string) $id ); ?>" data-ai-narration-cache-status="<?php echo esc_attr( $state ); ?>" data-ai-narration-cache-signature="<?php echo esc_attr( $this->cache_row_signature( $row ) ); ?>"><td><strong><a href="<?php echo esc_url( get_edit_post_link( $id, 'raw' ) ); ?>"><?php echo esc_html( $title ); ?></a></strong><span class="description">#<?php echo esc_html( (string) $id ); ?> · <?php echo esc_html( ucfirst( (string) $row['post_type'] ) ); ?></span></td><td><span class="ai-narration-cache-status ai-narration-cache-status--<?php echo esc_attr( $state ); ?>"><?php echo esc_html( $labels[ $state ] ?? ucfirst( $state ) ); ?></span></td><td><?php echo esc_html( $generated ); ?></td><td><?php echo esc_html( $audio ); ?></td><td><?php echo esc_html( (string) $row['voice'] ?: '—' ); ?><br><span class="description"><?php echo esc_html( $provider_label . ' · ' . (string) $row['model'] ); ?></span></td><td><div class="ai-narration-row-actions"><?php if ( ! empty( $urls ) ) : ?><button type="button" class="button ai-narration-cache-row-play" data-ai-narration-cache-play data-post-id="<?php echo esc_attr( (string) $id ); ?>" data-article-title="<?php echo esc_attr( $title ); ?>" data-audio-urls="<?php echo esc_attr( (string) wp_json_encode( $urls ) ); ?>" aria-label="<?php echo esc_attr( sprintf( __( 'Play cached narration for %s', 'ai-narration' ), $title ) ); ?>" aria-controls="ai-narration-cache-audition" aria-pressed="false"><span class="ai-narration-cache-row-play__label" data-ai-narration-cache-row-play-label><?php esc_html_e( 'Play', 'ai-narration' ); ?></span></button><?php endif; ?><a class="button" href="<?php echo esc_url( wp_nonce_url( admin_url( 'admin-post.php?action=ai_narration_regenerate_article&post_id=' . $id ), 'ai_narration_regenerate_article_' . $id ) ); ?>"><?php echo esc_html( $generate_label ); ?></a></div></td></tr><?php if ( 'failed' === $state && ! empty( $row['error'] ) ) : ?><tr class="ai-narration-cache-alert-row" data-ai-narration-cache-alert data-post-id="<?php echo esc_attr( (string) $id ); ?>"><td class="ai-narration-cache-alert-title"><strong><?php echo esc_html( $title ); ?></strong></td><td class="ai-narration-cache-alert-message" colspan="5"><strong><?php esc_html_e( 'Details:', 'ai-narration' ); ?></strong> <?php echo esc_html( (string) $row['error'] ); ?></td></tr><?php endif; ?><?php
	}

	public function run_queue_now(): void { $this->require_admin( __( 'You are not allowed to run the AI Narration queue.', 'ai-narration' ) ); check_admin_referer( 'ai_narration_run_queue_now' ); $this->cache->run_due_queue_now(); wp_safe_redirect( self::settings_url() ); exit; }
	public function retry_failed(): void { $this->require_admin( __( 'You are not allowed to retry failed AI Narration jobs.', 'ai-narration' ) ); check_admin_referer( 'ai_narration_retry_failed' ); $this->cache->retry_failed_jobs(); wp_safe_redirect( self::settings_url() ); exit; }
	private function require_admin( string $message ): void { if ( ! current_user_can( 'manage_options' ) ) { wp_die( esc_html( $message ) ); } }

	public function add_meta_boxes(): void { $types = get_post_types( array( 'public' => true, 'show_ui' => true ), 'names' ); unset( $types['attachment'] ); foreach ( $types as $type ) { add_meta_box( 'ai-narration-eligibility', __( 'AI Narration', 'ai-narration' ), array( $this, 'render_meta_box' ), $type, 'side', 'default' ); } }
	public function render_meta_box( WP_Post $post ): void { $value = (string) get_post_meta( $post->ID, '_ai_narration_override', true ); $value = in_array( $value, array( 'enabled', 'disabled' ), true ) ? $value : 'inherit'; wp_nonce_field( 'ai_narration_save_override', 'ai_narration_override_nonce' ); ?><p><label><input type="radio" name="ai_narration_override" value="inherit" <?php checked( $value, 'inherit' ); ?>> <?php esc_html_e( 'Inherit automatic rules', 'ai-narration' ); ?></label></p><p><label><input type="radio" name="ai_narration_override" value="enabled" <?php checked( $value, 'enabled' ); ?>> <?php esc_html_e( 'Force enabled', 'ai-narration' ); ?></label></p><p><label><input type="radio" name="ai_narration_override" value="disabled" <?php checked( $value, 'disabled' ); ?>> <?php esc_html_e( 'Force disabled', 'ai-narration' ); ?></label></p><p class="description"><code>[ai_narration]</code><br><code>[ai_narration_stop]</code></p><?php }
	public function save_post_override( int $post_id ): void { if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) ) { return; } $nonce = sanitize_text_field( (string) wp_unslash( $_POST['ai_narration_override_nonce'] ?? '' ) ); if ( ! wp_verify_nonce( $nonce, 'ai_narration_save_override' ) || ! current_user_can( 'edit_post', $post_id ) ) { return; } $value = sanitize_key( (string) wp_unslash( $_POST['ai_narration_override'] ?? 'inherit' ) ); if ( in_array( $value, array( 'enabled', 'disabled' ), true ) ) { update_post_meta( $post_id, '_ai_narration_override', $value ); } else { delete_post_meta( $post_id, '_ai_narration_override' ); } }

	/** @return array<string,string> */
	public static function models(): array { return array( 'gpt-4o-mini-tts' => 'GPT-4o mini TTS (current alias)', 'gpt-4o-mini-tts-2025-12-15' => 'GPT-4o mini TTS (2025-12-15 snapshot)', 'gpt-4o-mini-tts-2025-03-20' => 'GPT-4o mini TTS (2025-03-20 snapshot)' ); }
	/** @return array<string,string> */
	public static function voices(): array { return array( 'cedar' => 'Cedar', 'marin' => 'Marin', 'alloy' => 'Alloy', 'ash' => 'Ash', 'ballad' => 'Ballad', 'coral' => 'Coral', 'echo' => 'Echo', 'fable' => 'Fable', 'nova' => 'Nova', 'onyx' => 'Onyx', 'sage' => 'Sage', 'shimmer' => 'Shimmer', 'verse' => 'Verse' ); }

	private function limit_string( string $text, int $limit ): string { return function_exists( 'mb_substr' ) ? mb_substr( $text, 0, $limit, 'UTF-8' ) : substr( $text, 0, $limit ); }
	private function limit_utf8_bytes( string $text, int $limit ): string { if ( strlen( $text ) <= $limit ) { return $text; } $candidate = substr( $text, 0, $limit ); while ( '' !== $candidate && 1 !== preg_match( '//u', $candidate ) ) { $candidate = substr( $candidate, 0, -1 ); } return $candidate; }
}