fix(theme): align reference layouts and restore passing contracts

Align homepage and category discovery, modern widgets, admin controls, quotes, and comments with the reference theme. Remove superseded paths and add rendering and behavior coverage. Update stale asset and finance contracts; all 760 Node tests and 139 widget assertions pass.

inc/helpers/aksrt-yiyan.php

@@ -9,47 +9,67 @@
 
 defined('ABSPATH') || exit;
 
+add_action('wp_ajax_aksrt_yiyan', 'aksrt_ajax_yiyan');
+add_action('wp_ajax_nopriv_aksrt_yiyan', 'aksrt_ajax_yiyan');
+
+if (!function_exists('aksrt_ajax_yiyan')) :
+	/** Return one random Chinese/English pair from the theme quote file. */
+	function aksrt_ajax_yiyan(): void {
+		$custom_file = WP_CONTENT_DIR . '/yiyan.txt';
+		$theme_file = get_template_directory() . '/yiyan/qv-yiyan.txt';
+		$file = is_readable($custom_file) ? $custom_file : $theme_file;
+		$lines = is_readable($file) ? file($file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) : false;
+		$pairs = [];
+
+		if (is_array($lines)) {
+			// The first line is the reference file's title; the rest alternate EN/CN.
+			array_shift($lines);
+			$lines = array_values(array_map('trim', $lines));
+			for ($i = 0, $length = count($lines); $i + 1 < $length; $i += 2) {
+				if ($lines[$i] !== '' && $lines[$i + 1] !== '') {
+					$pairs[] = ['en' => $lines[$i], 'cn' => $lines[$i + 1]];
+				}
+			}
+		}
+
+		if (!$pairs) {
+			wp_send_json_error(['message' => __('一言内容暂不可用', 'aksrt')], 503);
+		}
+
+		wp_send_json_success($pairs[array_rand($pairs)]);
+	}
+endif;
+
 if (!function_exists('aksrt_render_yiyan_block')) :
 	/**
 	 * Shared 一言 shell for single-post placements (and reusable markup).
 	 *
-	 * Hitokoto category `c` must be a letter a–l, or empty for mixed random.
-	 * Client loads quotes via parallel fetches when count > 1.
+	 * Reads bilingual pairs from the bundled reference file and supports the
+	 * same optional wp-content/yiyan.txt override used by the reference theme.
 	 *
 	 * @param array<string,mixed> $args {
 	 *     @type string $class    Extra CSS classes on the root.
-	 *     @type string $type     Category letter a–l, or empty for random.
-	 *     @type int    $count    Number of quotes to load (1–10).
-	 *     @type int    $interval Rotation interval in seconds.
-	 *     @type string $icon     Optional FA icon class; empty = no icon.
 	 * }
 	 */
 	function aksrt_render_yiyan_block(array $args = []): void {
+		echo aksrt_get_yiyan_markup($args); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Escaped by the markup helper.
+	}
+	function aksrt_get_yiyan_markup(array $args = []): string {
 		$class    = trim((string) ($args['class'] ?? 'aksrt-yiyan'));
-		$type_raw = strtolower(trim((string) ($args['type'] ?? '')));
-		$type     = preg_match('/^[a-l]$/', $type_raw) ? $type_raw : '';
-		$count    = max(1, min(10, (int) ($args['count'] ?? 5)));
-		$interval = max(3, min(30, (int) ($args['interval'] ?? 8)));
-		$icon     = sanitize_text_field((string) ($args['icon'] ?? ''));
 
 		if (strpos($class, 'aksrt-yiyan') === false) {
 			$class = trim($class . ' aksrt-yiyan');
 		}
-		?>
-		<div class="<?php echo esc_attr($class); ?>"
-			data-aksrt-yiyan
-			data-count="<?php echo esc_attr((string) $count); ?>"
-			data-interval="<?php echo esc_attr((string) $interval); ?>"
-			<?php echo $type !== '' ? ' data-type="' . esc_attr($type) . '"' : ''; ?>>
-			<div class="aksrt-yiyan__content">
-				<?php if ($icon !== '') : ?>
-					<i class="<?php echo esc_attr($icon); ?> aksrt-yiyan__icon" aria-hidden="true"></i>
-				<?php endif; ?>
-				<p class="aksrt-yiyan__text"><?php esc_html_e('加载中…', 'aksrt'); ?></p>
-				<p class="aksrt-yiyan__from"></p>
-			</div>
-			<div class="aksrt-yiyan__dots" aria-hidden="true"></div>
-		</div>
-		<?php
+		$html = '<div class="' . esc_attr($class) . '"'
+			. ' data-aksrt-yiyan'
+			. ' data-endpoint="' . esc_url(admin_url('admin-ajax.php')) . '"'
+			. ' data-toggle="tooltip"'
+			. ' title="' . esc_attr__('点击切换一言', 'aksrt') . '"'
+			. ' role="button" tabindex="0"'
+			. ' aria-label="' . esc_attr__('点击切换一言', 'aksrt') . '"'
+			. ' aria-live="polite">'
+			. '<div class="yiyan"><div class="en"></div><div class="cn">' . esc_html__('加载中…', 'aksrt') . '</div></div>'
+			. '</div>';
+		return $html;
 	}
 endif;