Split album-render.source.sh along its four seams (ar0)

album-render.source.sh bundled four concerns that change for unrelated
reasons. Extract three focused siblings, leaving album-render as the page
orchestrator:

  - album-tile-layout.source.sh    tile_layout_for, build_tile_block,
                                   build_subdivided_tile
  - album-thumbnail-html.source.sh build_preview_thumbnail,
                                   append_preview_grid
  - album-photo-select.source.sh   album_photo_files, album_page_records,
                                   splash_photo_files, random_splash_photo,
                                   randomphoto

album-render.source.sh keeps page assembly, the per-photo view/details
pages, navigation redirects, index/splash, and the job_pool_* plumbing.
Every function moved whole with no body/signature change. The
album_view_page_for_photo accessor and its private ALBUM_VIEW_PAGE_BY_PHOTO
map stay in album-render so the stats mini-album boundary is unchanged.
LIB_SOURCES (Justfile + src/shuriken.sh) sources the three new modules
before album-render. Regenerated bin/shuriken.

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

1 files changed, 111 insertions, 0 deletions

diff --git a/src/lib/album-photo-select.source.sh b/src/lib/album-photo-select.source.sh
new file mode 100644
index 0000000..0a889bc
--- /dev/null
+++ b/src/lib/album-photo-select.source.sh
@@ -0,0 +1,111 @@
+# Album photo listing and random selection. Split out of
+# album-render.source.sh (task ar0) so the "which photos are in this album, in
+# what order, and which one do we pick for a background/splash" concern lives
+# apart from the page orchestration, the tile-layout deciders and the thumbnail
+# HTML. This is selection POLICY (shuffle/sort, splash-requires-a-blur, seeded
+# random pick) and changes for different reasons than the rendering plumbing.
+#
+# These helpers are called by the orchestrator (album-render.source.sh) and by
+# the per-page render jobs at runtime; all libs are sourced before any code runs,
+# so availability does not depend on source order.
+
+album_photo_files() {
+    local -r photos_dir="$1"; shift
+
+    find "$DIST_DIR/$photos_dir" -maxdepth 1 -type f -printf '%f\n' \
+        | maybe_shuffle
+}
+
+# Group the album's photos into pages of at most MAXPREVIEWS, in their final
+# (shuffled/sorted) order. The result is emitted one line per page as a
+# tab-separated record "<page_num>\t<photo>\t<photo>..." so the caller can walk
+# pages without keeping every page in memory at once. Order is fully
+# deterministic (album_photo_files already applies the seeded shuffle), so the
+# downstream parallelism only changes timing, never which photo lands where.
+album_page_records() {
+    local -r photos_dir="$1"; shift
+    local photo
+    local -i num=1
+    local -i count=0
+    local line=''
+
+    while IFS= read -r photo; do
+        if (( count == MAXPREVIEWS )); then
+            printf '%d\t%s\n' "$num" "$line"
+            (( ++num ))
+            count=0
+            line=''
+        fi
+        if (( count == 0 )); then
+            line="$photo"
+        else
+            line="$line"$'\t'"$photo"
+        fi
+        (( ++count ))
+    done < <(album_photo_files "$photos_dir")
+
+    if (( count > 0 )); then
+        printf '%d\t%s\n' "$num" "$line"
+    fi
+}
+
+splash_photo_files() {
+    local -r photos_dir="$1"; shift
+    local -r blurs_dir="$1"; shift
+    local photo
+
+    while IFS= read -r photo; do
+        if [ -f "$DIST_DIR/$blurs_dir/$photo" ]; then
+            printf '%s\n' "$photo"
+        fi
+    done < <(
+        find "$DIST_DIR/$photos_dir" -maxdepth 1 -type f -printf '%f\n' \
+            | sort
+    )
+}
+
+random_splash_photo() {
+    local -r photos_dir="$1"; shift
+    local -r blurs_dir="$1"; shift
+    local -i index
+    local photo
+    local -a photos=()
+
+    while IFS= read -r photo; do
+        photos+=("$photo")
+    done < <(splash_photo_files "$photos_dir" "$blurs_dir")
+
+    if (( ${#photos[@]} == 0 )); then
+        printf 'ERROR: No splash photos found in %s with matching blurs in %s\n' \
+            "$(_display_path "$DIST_DIR/$photos_dir")" \
+            "$(_display_path "$DIST_DIR/$blurs_dir")" >&2
+        return 1
+    fi
+
+    index=$(random_index "photo:$photos_dir:splash" "${#photos[@]}")
+    printf '%s\n' "${photos[index]}"
+}
+
+randomphoto() {
+    local -r photos_dir="$1"; shift
+    local -r context="${1:-$photos_dir}"
+    local -i index
+    local photo
+    local -a photos=()
+
+    while IFS= read -r photo; do
+        photos+=("$photo")
+    done < <(
+        find "$DIST_DIR/$photos_dir" -maxdepth 1 -type f -printf '%f\n' \
+            | sort
+    )
+
+    if (( ${#photos[@]} == 0 )); then
+        printf 'ERROR: No photos found in %s\n' \
+            "$(_display_path "$DIST_DIR/$photos_dir")" >&2
+        return 1
+    fi
+
+    index=$(random_index "photo:$photos_dir:$context" "${#photos[@]}")
+    printf '%s\n' "${photos[index]}"
+}