Add large 2x2 feature tiles and a CSS-grid overview

Allow a single photo to be blown up into a large "feature" tile that
spans a 2x2 block of the album overview, controlled by a new
THUMB_FEATURE_PERCENT (0-100, default 10; 0 disables). Each tile rolls
for a feature first, then for a subdivision, otherwise stays a normal
square.

To pack mixed-size tiles (normal 1x1, subdivided 1x1, feature 2x2)
without gaps, the overview is now a real CSS grid with
grid-auto-flow: dense, so smaller tiles backfill the holes a 2x2 feature
would leave. Tile spacing moved from per-image padding to the grid gap.
Feature tiles reuse the img.thumb class and its dramatic hover.

THUMB_FEATURE_PERCENT is wired through the same layers as
THUMB_SUBDIVIDE_PERCENT: config defaults, 0..100 validation,
--print-config, the --feature CLI flag, the usage text, and the
shuriken.json / --dry-run metadata, with docs and tests updated.
Generated HTML and CSS pass the W3C Nu HTML checker and CSS validator.
Setting both percentages to 0 reproduces the previous all-1x1 grid.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

6 files changed, 46 insertions, 16 deletions

diff --git a/src/lib/album-metadata.source.sh b/src/lib/album-metadata.source.sh
index 3d38cbf..b74bf8f 100644
--- a/src/lib/album-metadata.source.sh
+++ b/src/lib/album-metadata.source.sh
@@ -210,6 +210,7 @@ _collect_generation_metadata() {
     _GENERATION_METADATA["settings_thumbheight"]="$THUMBHEIGHT"
     _GENERATION_METADATA["settings_maxpreviews"]="$MAXPREVIEWS"
     _GENERATION_METADATA["settings_subdivide_percent"]="$THUMB_SUBDIVIDE_PERCENT"
+    _GENERATION_METADATA["settings_feature_percent"]="$THUMB_FEATURE_PERCENT"
     _GENERATION_METADATA["settings_image_jobs"]="$IMAGE_JOBS"
     _GENERATION_METADATA["settings_random_seed"]="$RANDOM_SEED"
     _GENERATION_METADATA["settings_shuffle"]="$SHUFFLE"
@@ -267,6 +268,8 @@ _generation_metadata_json() {
         "$(_json_string "${_GENERATION_METADATA["settings_maxpreviews"]}")"
     printf '    "subdivide_percent": %s,\n' \
         "$(_json_string "${_GENERATION_METADATA["settings_subdivide_percent"]}")"
+    printf '    "feature_percent": %s,\n' \
+        "$(_json_string "${_GENERATION_METADATA["settings_feature_percent"]}")"
     printf '    "image_jobs": %s,\n' \
         "$(_json_string "${_GENERATION_METADATA["settings_image_jobs"]}")"
     printf '    "random_seed": %s,\n' \
@@ -349,6 +352,7 @@ collect_dry_run_plan() {
     plan_ref["thumbheight"]="$THUMBHEIGHT"
     plan_ref["maxpreviews"]="$MAXPREVIEWS"
     plan_ref["subdivide_percent"]="$THUMB_SUBDIVIDE_PERCENT"
+    plan_ref["feature_percent"]="$THUMB_FEATURE_PERCENT"
     plan_ref["image_jobs"]="$IMAGE_JOBS"
     plan_ref["random_seed"]="$RANDOM_SEED"
     plan_ref["shuffle"]="$SHUFFLE"
@@ -380,6 +384,7 @@ print_dry_run_plan() {
     printf 'Thumb height: %s\n' "${plan_ref["thumbheight"]}"
     printf 'Max previews per page: %s\n' "${plan_ref["maxpreviews"]}"
     printf 'Subdivide percent: %s\n' "${plan_ref["subdivide_percent"]}"
+    printf 'Feature percent: %s\n' "${plan_ref["feature_percent"]}"
     printf 'Image jobs: %s\n' "${plan_ref["image_jobs"]}"
     printf 'Random seed: %s\n' "${plan_ref["random_seed"]}"
     printf 'Shuffle: %s\n' "${plan_ref["shuffle"]}"
diff --git a/src/lib/album-render.source.sh b/src/lib/album-render.source.sh
index 63c0c57..d97d05f 100644
--- a/src/lib/album-render.source.sh
+++ b/src/lib/album-render.source.sh
@@ -220,11 +220,13 @@ append_preview_grid() {
     done
 }
 
-# Decide the layout for the next tile, printing "<layout> <photo-count>". A tile
-# is subdivided with THUMB_SUBDIVIDE_PERCENT probability, but only into a layout
-# that fits the photos still remaining on the page; otherwise it is a single
-# square thumbnail. Randomness reuses the seeded random_index, so builds are
-# reproducible when RANDOM_SEED is set (and varied otherwise).
+# Decide the layout for the next tile, printing "<layout> <photo-count>". Each
+# tile rolls first for a "feature" (one photo blown up to a 2x2 hero tile) with
+# THUMB_FEATURE_PERCENT probability, then for a subdivision with
+# THUMB_SUBDIVIDE_PERCENT probability (only into a layout that fits the photos
+# still remaining on the page); otherwise it is a single square thumbnail. The
+# feature and subdivide rolls use independent seeded random_index namespaces, so
+# builds stay reproducible when RANDOM_SEED is set (and varied otherwise).
 tile_layout_for() {
     local -ri remaining="$1"; shift
     local -r context="$1"; shift
@@ -232,6 +234,14 @@ tile_layout_for() {
     local -a counts=(2)
     local -i roll choice
 
+    # A feature tile always fits (it consumes a single photo), so roll for it
+    # first. THUMB_FEATURE_PERCENT == 0 disables it (the roll can never be < 0).
+    roll=$(random_index "feature:$context" 100)
+    if (( roll < THUMB_FEATURE_PERCENT )); then
+        printf 'feature 1\n'
+        return
+    fi
+
     # A single tile when subdivision is disabled, too few photos remain to fill
     # even the smallest subdivided layout (two_wide needs 2), or the roll misses.
     if (( remaining < 2 || THUMB_SUBDIVIDE_PERCENT == 0 )); then
@@ -259,9 +269,11 @@ tile_layout_for() {
 }
 
 # Render one tile's markup (no trailing newline). A "single" tile is the plain
-# square thumbnail, byte-identical to the previous per-thumbnail output; any
-# other layout is a subdivided tile. The tile's photos are the trailing args and
-# their preview numbers run from start_preview upward.
+# square thumbnail, byte-identical to the previous per-thumbnail output. A
+# "feature" tile is the same single thumbnail but with the 'feature' anchor class
+# that makes CSS span it across a 2x2 block. Any other layout is a subdivided
+# tile. The tile's photos are the trailing args and their preview numbers run
+# from start_preview upward.
 build_tile_block() {
     local -r thumbs_dir="$1"; shift
     local -r backhref="$1"; shift
@@ -271,13 +283,21 @@ build_tile_block() {
     local -a photos=("$@")
     local animation_class
 
-    if [ "$layout" = single ]; then
-        animation_class=$(random_animation_css_class slow "${photos[0]}")
-        build_preview_thumbnail \
-            "$thumbs_dir" "$backhref" "$page_num" "$start_preview" \
-            "${photos[0]}" "$animation_class"
-        return
-    fi
+    case "$layout" in
+        single|feature)
+            animation_class=$(random_animation_css_class slow "${photos[0]}")
+            # 'single' -> no anchor class (legacy output); 'feature' -> the
+            # 'feature' anchor class CSS spans across a 2x2 grid block.
+            local anchor_class=''
+            if [ "$layout" = feature ]; then
+                anchor_class='feature'
+            fi
+            build_preview_thumbnail \
+                "$thumbs_dir" "$backhref" "$page_num" "$start_preview" \
+                "${photos[0]}" "$animation_class" thumb "$anchor_class"
+            return
+            ;;
+    esac
     build_subdivided_tile \
         "$thumbs_dir" "$backhref" "$page_num" "$layout" "$start_preview" \
         "${photos[@]}"
diff --git a/src/lib/bootstrap.source.sh b/src/lib/bootstrap.source.sh
index 7fa5ea3..66193e3 100644
--- a/src/lib/bootstrap.source.sh
+++ b/src/lib/bootstrap.source.sh
@@ -29,6 +29,7 @@ usage() {
     --thumbheight VALUE
     --maxpreviews N
     --subdivide PERCENT
+    --feature PERCENT
     --image-jobs N
     --random-seed VALUE
     --splash
diff --git a/src/lib/config.print.source.sh b/src/lib/config.print.source.sh
index 401d84c..62ff145 100644
--- a/src/lib/config.print.source.sh
+++ b/src/lib/config.print.source.sh
@@ -34,6 +34,7 @@ print_config() {
     print_shell_assignment THUMBHEIGHT "$THUMBHEIGHT"
     print_shell_assignment MAXPREVIEWS "$MAXPREVIEWS"
     print_shell_assignment THUMB_SUBDIVIDE_PERCENT "$THUMB_SUBDIVIDE_PERCENT"
+    print_shell_assignment THUMB_FEATURE_PERCENT "$THUMB_FEATURE_PERCENT"
     print_shell_assignment IMAGE_JOBS "$IMAGE_JOBS"
     print_shell_assignment IMAGEMAGICK_TIMEOUT "$IMAGEMAGICK_TIMEOUT"
     print_shell_assignment RANDOM_SEED "$RANDOM_SEED"
diff --git a/src/lib/config.source.sh b/src/lib/config.source.sh
index 538724f..67ddade 100644
--- a/src/lib/config.source.sh
+++ b/src/lib/config.source.sh
@@ -47,8 +47,10 @@ apply_config_defaults() {
     SPLASH_PAGE="${SPLASH_PAGE:-yes}"
     STATS_PAGE="${STATS_PAGE:-no}"
     # Optional with a default (unlike the required THUMBHEIGHT): the percent
-    # chance a preview tile is subdivided into smaller thumbnails. 0 disables it.
+    # chance a preview tile is subdivided into smaller thumbnails, and the
+    # percent chance it becomes a large 2x2 "feature" tile. 0 disables either.
     THUMB_SUBDIVIDE_PERCENT="${THUMB_SUBDIVIDE_PERCENT:-30}"
+    THUMB_FEATURE_PERCENT="${THUMB_FEATURE_PERCENT:-10}"
     SYNC_DELETE="${SYNC_DELETE:-yes}"
     TARBALL_INCLUDE="${TARBALL_INCLUDE:-no}"
     TARBALL_SUFFIX="${TARBALL_SUFFIX:-.tar}"
diff --git a/src/lib/config.validate.source.sh b/src/lib/config.validate.source.sh
index e3c55e7..7b1421b 100644
--- a/src/lib/config.validate.source.sh
+++ b/src/lib/config.validate.source.sh
@@ -287,6 +287,7 @@ validate_common_config() {
     validate_positive_integer_config_var THUMBHEIGHT || return
     validate_positive_integer_config_var MAXPREVIEWS || return
     validate_percentage_config_var THUMB_SUBDIVIDE_PERCENT || return
+    validate_percentage_config_var THUMB_FEATURE_PERCENT || return
     validate_positive_integer_config_var IMAGE_JOBS || return
     validate_positive_integer_config_var IMAGEMAGICK_TIMEOUT || return
     validate_positive_integer_config_var TAR_TIMEOUT || return