feat: deterministic image composer — OG + square variants, branding, baked caption (v0.17.0)

Commit 2 (final scope) of the in-plugin editorial image pipeline
(ARCHITECTURE.md #21). A deterministic local composer now runs between
provider bytes and sideload: Image A yields a corner-marked featured
(1200x632) + branded OG (1200x630, teal band, logo, baked caption in
Poppins SemiBold) + square card (1080x1080, cream panel, Poppins Bold,
teal footer with the reverse lockup); Image B gets the corner mark only.

- Capability ladder: imagick (full compositing) -> wp_get_image_editor
  resize-only (unbranded, WARNING once) -> pass-through (WARNING once);
  probe cached in prautoblogger_image_compose_capability, fingerprinted
  by PHP version + imagick/gd presence so host flips auto-invalidate.
  compose() never throws; composition can never fail a publish.
- Variants sideloaded with a role filename suffix; attachment meta
  _prautoblogger_image_role + _prautoblogger_base_attachment_id; post
  meta _prautoblogger_og_image_id (frozen for the rebuilt SEO stage) +
  _prautoblogger_square_image_id. No cost-tracker rows ($0 local stage;
  duration logged on the image_composer channel).
- New Images settings: compose_enabled ('1'), compose_variants
  ('og,square'), featured_mark_enabled ('1') — read at point of use.
  Geometry ships as Layout defaults behind the
  prautoblogger_image_compose_layout filter.
- Vendored brand rasters (assets/brand) + bundled OFL Poppins faces
  (assets/fonts) for per-environment byte-stable output (stripImage +
  PNG date/time chunks excluded). Validated on Hostinger PHP 8.3.30 /
  ImageMagick 7.1.1-43: php -l clean on all touched files, double
  render byte-identical (sha256), exact variant geometry.
- Fix: featured/Image B alt text is the editorial caption (was the
  model name); model still persists in _prautoblogger_image_model.
- Image_Attacher extracted from Image_Pipeline (300-line compliance);
  sideloader gains an optional filename suffix param (back-compat '').
- Version 0.16.0 -> 0.17.0 + CHANGELOG + ARCHITECTURE.md #21 +
  CONVENTIONS.md composer guide in this commit. Unit tests: layout
  clamp boundaries, capability ladder, cache invalidation, attacher
  meta-linking, pipeline integration, imagick determinism (gated).

Agent-Session: engineer-prautoblogger-image-composer-20260611

includes/core/class-image-media-sideloader.php

@@ -36,11 +36,13 @@ class PRAutoBlogger_Image_Media_Sideloader {
 	 *     latency_ms: int,
 	 * } $image_data Raw image bytes + metadata from PRAutoBlogger_Image_Provider_Interface.
 	 * @param int    $post_id Target post ID to attach the image to.
-	 * @param string $alt_text Alt text for the image (from the generation prompt).
+	 * @param string $alt_text Alt text for the image (the editorial caption).
+	 * @param string $filename_suffix Optional role hint appended to the filename
+	 *                                (e.g. 'og', 'square' for composed variants).
 	 *
 	 * @return int|\WP_Error Attachment ID on success, WP_Error on failure.
 	 */
-	public function sideload_image( array $image_data, int $post_id, string $alt_text = '' ) {
+	public function sideload_image( array $image_data, int $post_id, string $alt_text = '', string $filename_suffix = '' ) {
 		// WordPress media functions live in wp-admin/includes/ and are NOT
 		// loaded automatically in cron or REST contexts. Load them if missing.
 		// Why: WP-Cron runs as a frontend request, so admin-only files like
@@ -64,7 +66,7 @@ class PRAutoBlogger_Image_Media_Sideloader {
 
 		// Prepare file array for media_handle_sideload().
 		$file_array = array(
-			'name'     => $this->generate_filename( $image_data['model'], $image_data['width'], $image_data['height'] ),
+			'name'     => $this->generate_filename( $image_data['model'], $image_data['width'], $image_data['height'], $filename_suffix ),
 			'tmp_name' => $temp_file,
 		);
 
@@ -135,16 +137,18 @@ class PRAutoBlogger_Image_Media_Sideloader {
 	 * @param string $model Model name (e.g., 'flux-1-schnell').
 	 * @param int    $width Image width.
 	 * @param int    $height Image height.
+	 * @param string $suffix Optional role hint (e.g. 'og', 'square'); back-compat default ''.
 	 *
 	 * @return string Sanitized filename.
 	 */
-	private function generate_filename( string $model, int $width, int $height ): string {
+	private function generate_filename( string $model, int $width, int $height, string $suffix = '' ): string {
 		$base = sprintf(
-			'prautoblogger_%s_%dx%d_%s',
+			'prautoblogger_%s_%dx%d_%s%s',
 			sanitize_title( $model ),
 			$width,
 			$height,
-			gmdate( 'Y-m-d_H-i-s' )
+			gmdate( 'Y-m-d_H-i-s' ),
+			'' !== $suffix ? '_' . sanitize_title( $suffix ) : ''
 		);
 
 		return $base . '.png'; // Default to PNG — most image models output PNG.