wn0 batch preview-thumbnail rendering per page

Each thumbnail on a preview page (page-N.html) used to be rendered by its
own "template preview" call, paying the full source_template_file cost --
an "env -i bash" invocation -- per thumbnail. With MAXPREVIEWS thumbnails
per page that was N template renders per page just for the grid.

render_full_preview_page now builds the markup for ALL of a page's
thumbnails in bash (build_preview_thumbnail / append_preview_thumbnail)
and emits the whole grid in ONE render via a new previewpage.tmpl that
takes the pre-built HTML through a context_raw "preview_thumbs" field --
the same pattern the stats filter galleries (camera.tmpl) already use.
Per-thumbnail markup is byte-identical to the old preview.tmpl output:
same <a name=... href=...><img class='thumb <anim>' .../></a> structure,
order, HTML escaping and seeded "slow" animation class. Header and footer
stay as their own template calls, so a page now costs ~1 previewpage
render + header/footer instead of N + chrome.

The parallel job-pool integration and failure contract are unchanged:
each preview page is still one background render job. Added the
render_preview_thumbs_html field spec (hn0 dispatch pattern, context_raw
kind), registered previewpage in the validate_template_dir required
templates and in the required-context-vars test expectations, and pointed
the four generation template-failure tests at previewpage.tmpl (generation
no longer renders preview.tmpl). The standalone "template preview" engine
unit tests keep exercising preview.tmpl, which still ships.

Verified byte-identical output: generated the fixture album (including a
spaces/special-char filename) twice with RANDOM_SEED=42 using the parent
commit's bin/shuriken vs the new bin; every .html file is identical.
just test, just shellcheck, just check-generated and git diff --check all
pass.

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

3 files changed, 56 insertions, 14 deletions

diff --git a/src/lib/album-render.source.sh b/src/lib/album-render.source.sh
index ff86727..9bae930 100644
--- a/src/lib/album-render.source.sh
+++ b/src/lib/album-render.source.sh
@@ -96,12 +96,19 @@ render_full_preview_page() {
         render_previous_page_link "$page_name" "$html_dir" "$prev_page"
     fi
 
+    # Batch all of this page's thumbnails into ONE template call. Building the
+    # markup in bash and emitting it via the raw "preview_thumbs" field collapses
+    # what used to be N "template preview" renders (one env -i bash per
+    # thumbnail) into a single previewpage render per page.
+    local preview_thumbs=''
     for photo in "$@"; do
         (( ++preview_num ))
-        render_preview_thumbnail \
-            "$page_name" "$html_dir" "$thumbs_dir" "$backhref" \
-            "$page_num" "$preview_num" "$photo"
+        append_preview_thumbnail preview_thumbs \
+            "$thumbs_dir" "$backhref" "$page_num" "$preview_num" "$photo"
     done
+    template previewpage "$page_name.html" \
+        html_dir "$html_dir" \
+        preview_thumbs "$preview_thumbs"
 
     if [ -n "$next_page" ]; then
         finish_preview_page_with_next \
@@ -165,25 +172,58 @@ queue_preview_page_render_job() {
     render_job_labels_ref["$!"]="template render job for preview $page_name"
 }
 
-render_preview_thumbnail() {
-    local -r page_name="$1"; shift
-    local -r html_dir="$1"; shift
+# Append one thumbnail's markup to a page's accumulating thumbnail-grid buffer.
+# Produces exactly the bytes the old per-thumbnail preview.tmpl emitted (the
+# <a name=... href=...><img class='thumb <anim>' .../></a> block), so batching
+# all thumbnails into one previewpage render stays byte-identical. Every
+# interpolated value is HTML-escaped like the template's context_html fields; the
+# seeded "slow" animation class is preserved exactly. Blocks are separated by a
+# newline; the previewpage template adds the single trailing newline, matching
+# the old N sequential renders.
+append_preview_thumbnail() {
+    local -n buffer_ref="$1"; shift
     local -r thumbs_dir="$1"; shift
     local -r backhref="$1"; shift
     local -r page_num="$1"; shift
     local -r preview_num="$1"; shift
     local -r photo_file="$1"; shift
     local animation_class
+    local block
 
     animation_class=$(random_animation_css_class slow "$photo_file")
-    template preview "$page_name.html" \
-        html_dir "$html_dir" \
-        backhref "$backhref" \
-        thumbs_dir "$thumbs_dir" \
-        page_num "$page_num" \
-        preview_num "$preview_num" \
-        photo "$photo_file" \
-        animation_class "$animation_class"
+    block=$(build_preview_thumbnail \
+        "$thumbs_dir" "$backhref" "$page_num" "$preview_num" "$photo_file" \
+        "$animation_class")
+    if [ -z "$buffer_ref" ]; then
+        buffer_ref="$block"
+    else
+        buffer_ref+=$'\n'"$block"
+    fi
+}
+
+# Render the HTML for a single preview thumbnail (HTML-escaping every value the
+# way preview.tmpl's context_html fields did). Returned without a trailing
+# newline so callers control separators.
+build_preview_thumbnail() {
+    local -r thumbs_dir="$1"; shift
+    local -r backhref="$1"; shift
+    local -r page_num="$1"; shift
+    local -r preview_num="$1"; shift
+    local -r photo_file="$1"; shift
+    local -r animation_class="$1"; shift
+    local photo_html
+    local anim_html
+    local backhref_html
+    local thumbs_dir_html
+
+    photo_html=$(_html_escape "$photo_file")
+    anim_html=$(_html_escape "$animation_class")
+    backhref_html=$(_html_escape "$backhref")
+    thumbs_dir_html=$(_html_escape "$thumbs_dir")
+    printf '<a name=%s href=%s>\n' \
+        "'$photo_html'" "'$page_num-$preview_num.html'"
+    printf "  <img class='thumb %s' src='%s/%s/%s' />\n</a>" \
+        "$anim_html" "$backhref_html" "$thumbs_dir_html" "$photo_html"
 }
 
 render_view_page() {
diff --git a/src/lib/config.validate.source.sh b/src/lib/config.validate.source.sh
index fda20f0..7519094 100644
--- a/src/lib/config.validate.source.sh
+++ b/src/lib/config.validate.source.sh
@@ -101,6 +101,7 @@ validate_template_dir() {
         next
         prev
         preview
+        previewpage
         redirect
         view
     )
diff --git a/src/lib/template.source.sh b/src/lib/template.source.sh
index 13a2988..cd44a45 100644
--- a/src/lib/template.source.sh
+++ b/src/lib/template.source.sh
@@ -165,6 +165,7 @@ declare -ra TEMPLATE_RENDER_FIELD_SPECS=(
     'render_photos_dir_html|context_html|photos_dir|photos_dir|splash details view'
     'render_prev_html|context_html|prev|prev|prev'
     'render_preview_num_html|context_html|preview_num|preview_num|preview details view'
+    'render_preview_thumbs_html|context_raw|preview_thumbs|preview_thumbs|previewpage'
     'render_redirect_page_html|context_html|redirect_page|redirect_page|redirect'
     'render_show_header_bar|context_raw|show_header_bar|show_header_bar|header'
     'render_stats_body_html|context_raw|stats_body|stats_body|stats'