v1.7.0: readability & UX pass

php/home.php

@@ -52,11 +52,16 @@
 <!-- Post list (titles only) -->
 <div class="post-list">
   <?php foreach ($content as $page) : ?>
-    <article class="post-list-item">
+    <?php $bdCover = $page->coverImage(); ?>
+    <article class="post-list-item<?php echo $bdCover ? ' has-thumb' : ''; ?>">
 
       <!-- Load Bludit Plugins: Page Begin -->
       <?php Theme::plugins('pageBegin'); ?>
 
+      <div class="post-list-row">
+
+      <div class="post-list-main">
+
       <div class="post-list-head">
         <a href="<?php echo $page->permalink(); ?>">
           <h2 class="post-list-title"><?php echo blowfish_text($page->title()); ?></h2>
@@ -101,6 +106,17 @@
         </div>
       <?php endif ?>
 
+      </div><!-- /.post-list-main -->
+
+      <!-- Cover thumbnail -->
+      <?php if ($bdCover) : ?>
+        <a class="post-list-thumb" href="<?php echo $page->permalink(); ?>" tabindex="-1" aria-hidden="true">
+          <img src="<?php echo htmlspecialchars($bdCover, ENT_QUOTES, 'UTF-8'); ?>" alt="" loading="lazy" decoding="async" />
+        </a>
+      <?php endif ?>
+
+      </div><!-- /.post-list-row -->
+
       <!-- Load Bludit Plugins: Page End -->
       <?php Theme::plugins('pageEnd'); ?>
 

php/icons.php

@@ -55,6 +55,28 @@ if (!function_exists('blowfish_icon')) {
 		return DOMAIN_THEME . $rel . ($v ? '?v=' . $v : '');
 	}
 
+	// Inject width/height attributes into local-upload <img> tags that lack
+	// them, so the browser reserves the box before the image loads (no CLS).
+	// Only touches images served from this site's uploads folder; remote
+	// images and tags that already declare a width are left alone.
+	function blowfish_img_dimensions($html) {
+		if (!defined('DOMAIN_UPLOADS') || !defined('PATH_UPLOADS')) { return $html; }
+		return preg_replace_callback('/<img\b[^>]*>/i', function ($m) {
+			$tag = $m[0];
+			if (preg_match('/\b(?:width|height)\s*=/i', $tag)) { return $tag; }
+			if (!preg_match('/\bsrc=["\']([^"\']+)["\']/i', $tag, $src)) { return $tag; }
+			$url = html_entity_decode($src[1], ENT_QUOTES, 'UTF-8');
+			if (strpos($url, DOMAIN_UPLOADS) !== 0) { return $tag; }
+			$rel = rawurldecode(substr($url, strlen(DOMAIN_UPLOADS)));
+			if ($rel === '' || strpos($rel, '..') !== false) { return $tag; }
+			$file = PATH_UPLOADS . $rel;
+			if (!is_file($file)) { return $tag; }
+			$size = @getimagesize($file);
+			if (!$size || empty($size[0]) || empty($size[1])) { return $tag; }
+			return preg_replace('/<img\b/i', '<img width="' . (int) $size[0] . '" height="' . (int) $size[1] . '"', $tag, 1);
+		}, $html);
+	}
+
 	// Map a theme key to its toggle icon name.
 	function blowfish_theme_icon($theme) {
 		$map = array(

php/page.php

@@ -102,11 +102,15 @@
 				// Lazy-load + async-decode in-content images that don't already
 				// set a loading attribute. Operates on the rendered HTML, so
 				// carousel/tabs fences (still raw text inside <pre>) are untouched.
-				echo preg_replace(
+				$bdContent = preg_replace(
 					'/<img(?![^>]*\bloading=)/i',
 					'<img loading="lazy" decoding="async"',
 					$page->content()
 				);
+				// Add width/height to local-upload images so the layout doesn't
+				// shift as they load (CLS). CSS `img { height: auto }` keeps the
+				// aspect ratio responsive.
+				echo blowfish_img_dimensions($bdContent);
 			?>
 		</div>