jekyll-theme-zer0 1.19.1 → 1.20.2

data/scripts/README.md

@@ -21,6 +21,8 @@ scripts/
 │   └── preview_generator.py  # Python preview image generator
 ├── features/              # Feature-specific scripts
 │   ├── generate-preview-images     # AI preview image generator
+│   ├── pixelate-preview-images     # Shrink preview banners (pixelate + PNG-8)
+│   ├── pixelate_images.py          # Pure-stdlib pixelate/quantize engine
 │   ├── install-preview-generator   # Preview generator installer
 │   └── validate_preview_urls.py    # Preview URL validator
 ├── utils/                 # Utility scripts
@@ -123,6 +125,43 @@ AI Providers:
   xai       - xAI Grok image generation (requires XAI_API_KEY)
 ```
 
+#### `pixelate-preview-images`
+Pixelate + palette-quantize the preview banners so they are dramatically smaller
+files while retaining the retro pixel-art look. Pure Python stdlib (no
+ImageMagick / Pillow / pngquant needed) — it downsamples the image and reduces
+it to an indexed PNG-8 palette. Typical savings on the AI-generated banners are
+~90% (e.g. a 2.7 MB banner becomes ~230 KB).
+
+```bash
+# Preview the savings for every banner (no changes), 4 workers:
+./scripts/features/pixelate-preview-images --dry-run -j 4
+
+# Optimize all banners in place:
+./scripts/features/pixelate-preview-images -j 4
+
+# Chunkier pixel-art look for one image:
+./scripts/features/pixelate-preview-images --block 6 --colors 64 \
+    assets/images/previews/about.png
+
+Options (forwarded to scripts/features/pixelate_images.py):
+  -n, --dry-run         Report savings without writing
+  --colors N            Palette size 2-256 (default: 256)
+  --bits N              Colour precision 1-8 while quantizing (default: 6)
+  --max-width N         Downscale so width <= N, keep aspect (default: 1024)
+  --scale F             Scale factor, e.g. 0.5
+  --block N             Average NxN source pixels per output pixel (chunky)
+  --filter nearest|box  Downsample filter (default: nearest)
+  --upscale             Keep original WxH (chunky pixels) instead of reduced
+  --backup              Keep <file>.orig when writing in place
+  --force               Write even if the result is not smaller
+  -j, --jobs N          Parallel worker processes (default: 1)
+```
+
+With no path argument it processes `preview_images.output_dir` from
+`_config.yml` (default `assets/images/previews`). Non-PNG and 16-bit/interlaced
+inputs are skipped gracefully. The engine has a built-in `--selftest`, exercised
+by `scripts/test/lib/test_pixelate_images.sh`.
+
 #### `install-preview-generator`
 Install the preview image generator feature.
 

data/scripts/bin/validate

@@ -35,7 +35,7 @@ DESCRIPTION:
 DEFAULT CHECKS:
     - Required repository files
     - Gemspec parse
-    - Version consistency between version.rb, package.json, and gemspec
+    - Version consistency between version.rb, package.json, gemspec, and Gemfile.lock
     - YAML parse for root config, _data, and .github/config files
     - Active configuration contract and config-file classification
     - Navigation data shape
@@ -241,6 +241,16 @@ if File.file?('package.json')
   versions['package.json'] = JSON.parse(File.read('package.json', encoding: 'UTF-8')).fetch('version').to_s
 end
 
+# Gemfile.lock pins the gem's own version in its PATH specs block. It drifts
+# from version.rb when a release path bumps the version without re-locking
+# (the exact failure that left the lock at 1.19.1 while version.rb said 1.19.0).
+if File.file?('Gemfile.lock')
+  lock = File.read('Gemfile.lock')
+  if (match = lock.match(/^\s*jekyll-theme-zer0 \(([^)]+)\)\s*$/))
+    versions['Gemfile.lock'] = match[1].to_s
+  end
+end
+
 expected = versions.values.first
 mismatches = versions.select { |_file, version| version != expected }
 

data/scripts/dev/css-diff.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# ============================================================================
+# css-diff.sh — compiled-CSS regression guard for the SCSS refactor
+# ----------------------------------------------------------------------------
+# Compares two compiled main.css files (Jekyll `style: expanded` output):
+#   1. POSITIONAL diff  — empty means byte-identical (ignoring blank-line/WS
+#      churn). Expected for true zero-diff relocations.
+#   2. SORTED-CONTENT diff — empty means the exact same set of CSS lines exists
+#      in both files, only their order differs. This is the invariant we want
+#      for "pure relocation" phases: no declaration value changed, a block just
+#      moved position in the cascade.
+#
+# Usage: scripts/dev/css-diff.sh OLD.css NEW.css
+# Exit:  0 if sorted-content identical (safe), 1 otherwise.
+# ============================================================================
+set -uo pipefail
+
+OLD="${1:?usage: css-diff.sh OLD.css NEW.css}"
+NEW="${2:?usage: css-diff.sh OLD.css NEW.css}"
+
+# Normalize: drop blank lines, trim leading/trailing whitespace per line.
+norm() { sed -e 's/[[:space:]]*$//' -e 's/^[[:space:]]*//' "$1" | grep -v '^$'; }
+
+echo "=== POSITIONAL diff (empty = byte-identical modulo whitespace) ==="
+if diff <(norm "$OLD") <(norm "$NEW"); then
+  echo "(positional: identical)"
+  POS=0
+else
+  POS=1
+fi
+
+echo ""
+echo "=== SORTED-CONTENT diff (empty = same rule content, order-only change) ==="
+if diff <(norm "$OLD" | sort) <(norm "$NEW" | sort); then
+  echo "(sorted-content: identical — no value changed)"
+  SORTED=0
+else
+  SORTED=1
+fi
+
+echo ""
+if [ "$POS" -eq 0 ]; then
+  echo "RESULT: zero-diff (identical output)."
+elif [ "$SORTED" -eq 0 ]; then
+  echo "RESULT: relocation-only (content identical, order changed). Review positional diff for cascade safety."
+else
+  echo "RESULT: CONTENT CHANGED. Review the sorted-content diff above — declarations were added/removed/edited."
+fi
+exit "$SORTED"

data/scripts/dev/shot.js

@@ -0,0 +1,37 @@
+// Screenshot helper for the SCSS refactor — captures key pages at several
+// viewports against the running dev server. Usage:
+//   node scripts/dev/shot.js <label> [path] [skin]
+// Outputs PNGs to /tmp/shots/<label>-<vw>.png. Reused across phases to compare
+// before/after for cascade-sensitive or pixel-changing changes.
+const { chromium } = require('@playwright/test');
+const fs = require('fs');
+
+const label = process.argv[2] || 'shot';
+const path = process.argv[3] || '/';
+const skin = process.argv[4] || null;
+const BASE = process.env.BASE_URL || 'http://localhost:4000';
+const VWS = [
+  { name: 'lg', width: 1280, height: 800 },
+  { name: 'md', width: 820, height: 1100 },
+  { name: 'sm', width: 390, height: 850 },
+];
+
+(async () => {
+  fs.mkdirSync('/tmp/shots', { recursive: true });
+  const browser = await chromium.launch();
+  for (const vw of VWS) {
+    const ctx = await browser.newContext({ viewport: { width: vw.width, height: vw.height } });
+    const page = await ctx.newPage();
+    if (skin) {
+      await page.addInitScript((s) => {
+        try { localStorage.setItem('zer0-skin', s); } catch (e) {}
+      }, skin);
+    }
+    await page.goto(BASE + path, { waitUntil: 'networkidle' });
+    const out = `/tmp/shots/${label}-${vw.name}.png`;
+    await page.screenshot({ path: out, fullPage: false });
+    console.log('wrote', out);
+    await ctx.close();
+  }
+  await browser.close();
+})();

data/scripts/features/generate-preview-images

@@ -91,9 +91,15 @@ fi
 # =============================================================================
 # Configuration Loading
 # =============================================================================
-# Priority: CLI args > Environment variables > _config.yml > Defaults
+# Priority (per file): author preview overrides (_data/authors.yml) >
+#                       CLI args > Environment variables > _config.yml > Defaults
+# A post's `author:` may point at an entry in _data/authors.yml that carries a
+# `preview:` block (style / style_modifiers / size / quality / model). Those win
+# over the site-wide preview_images config for that post's banner, giving each
+# AI author persona a distinct, recognisable art style.
 
 CONFIG_FILE="$PROJECT_ROOT/_config.yml"
+AUTHORS_FILE="$PROJECT_ROOT/_data/authors.yml"
 
 # Function to read config value from _config.yml using grep (handles YAML anchors)
 read_config() {
@@ -283,6 +289,13 @@ CONFIGURATION:
     Default settings are loaded from _config.yml under 'preview_images' section.
     Environment variables override config file settings.
 
+    PER-AUTHOR ART STYLE:
+    A post's `author:` may reference an entry in _data/authors.yml that defines a
+    `preview:` block (style, style_modifiers, size, quality, model). When present,
+    those values override the site-wide preview_images settings for that post's
+    banner only — giving each AI author persona (e.g. cassandra, vega) a distinct
+    look. Other posts keep the default style.
+
 EXAMPLES:
     # List all files missing preview images
     ./scripts/generate-preview-images.sh --list-missing
@@ -482,6 +495,73 @@ except:
     echo "$result"
 }
 
+# Read a per-author preview override from _data/authors.yml
+# Usage: get_author_preview_value <author_key> <setting>
+#   e.g. get_author_preview_value cassandra style
+# Returns the value (or empty string when the author / setting is absent).
+get_author_preview_value() {
+    local author_key="$1"
+    local setting="$2"
+
+    [[ -z "$author_key" || ! -f "$AUTHORS_FILE" ]] && return 0
+
+    local result=""
+    if [[ "${YAML_PARSER:-python}" == "yq" ]]; then
+        # Capture the whole value (do NOT `head -1`) so a multi-line literal/folded
+        # scalar survives intact, matching the python3 branch below; trim a single
+        # trailing newline that yq appends.
+        result=$(yq eval ".\"${author_key}\".preview.${setting} // \"\"" "$AUTHORS_FILE" 2>/dev/null)
+        result="${result%$'\n'}"
+        [[ "$result" == "null" ]] && result=""
+    else
+        result=$(AUTHOR_KEY="$author_key" SETTING="$setting" AUTHORS_FILE="$AUTHORS_FILE" python3 -c '
+import os, yaml
+try:
+    data = yaml.safe_load(open(os.environ["AUTHORS_FILE"])) or {}
+    author = data.get(os.environ["AUTHOR_KEY"]) or {}
+    preview = author.get("preview") or {}
+    val = preview.get(os.environ["SETTING"])
+    if val is not None:
+        print(str(val).strip())
+except Exception:
+    pass
+' 2>/dev/null)
+    fi
+
+    echo "$result"
+}
+
+# Apply a post author's per-author preview overrides (from _data/authors.yml) on
+# top of the current image settings. MUST be called from a function that has
+# already declared `local IMAGE_STYLE` (+ IMAGE_STYLE_MODIFIERS / IMAGE_SIZE /
+# IMAGE_QUALITY / IMAGE_MODEL) — bash dynamic scoping lets this helper reassign
+# those caller locals, scoping the override to the current file. Call it only at
+# the point an image/prompt is actually built, so --list-missing stays clean and
+# already-satisfied files don't pay for the lookup.
+apply_author_preview_overrides() {
+    local author="$1"
+    [[ -z "$author" ]] && return 0
+
+    local ov_style ov_mods ov_size ov_quality ov_model
+    ov_style=$(get_author_preview_value "$author" "style")
+    ov_mods=$(get_author_preview_value "$author" "style_modifiers")
+    ov_size=$(get_author_preview_value "$author" "size")
+    ov_quality=$(get_author_preview_value "$author" "quality")
+    ov_model=$(get_author_preview_value "$author" "model")
+
+    [[ -n "$ov_style" ]]   && IMAGE_STYLE="$ov_style"
+    [[ -n "$ov_mods" ]]    && IMAGE_STYLE_MODIFIERS="$ov_mods"
+    [[ -n "$ov_size" ]]    && IMAGE_SIZE="$ov_size"
+    [[ -n "$ov_quality" ]] && IMAGE_QUALITY="$ov_quality"
+    [[ -n "$ov_model" ]]   && IMAGE_MODEL="$ov_model"
+
+    if [[ -n "$ov_style" || -n "$ov_mods" || -n "$ov_size" || -n "$ov_quality" || -n "$ov_model" ]]; then
+        info "  ↳ Author '$author' preview overrides applied (style from _data/authors.yml)"
+        debug "Author override style: ${IMAGE_STYLE:0:120}..."
+    fi
+    return 0
+}
+
 # Extract post content (without front matter)
 extract_content() {
     local file="$1"
@@ -983,15 +1063,33 @@ process_file() {
     fi
     
     # Get metadata
-    local title description categories preview
+    local title description categories preview author
     title=$(get_yaml_value "$front_matter" "title")
     description=$(get_yaml_value "$front_matter" "description")
     categories=$(get_yaml_value "$front_matter" "categories")
     preview=$(get_yaml_value "$front_matter" "preview")
-    
+    author=$(get_yaml_value "$front_matter" "author")
+
     debug "Title: $title"
     debug "Preview: $preview"
-    
+
+    # -------------------------------------------------------------------------
+    # Per-author art-style override (e.g. AI personas Cassandra / Vega).
+    # These `local`s shadow the global image settings for the duration of this
+    # function and everything it calls (generate_prompt, generate_image,
+    # build_enhance_prompt) via bash dynamic scoping — so each worker/file gets
+    # its author's style without leaking to other files, in serial or parallel.
+    # The actual lookup runs later, via apply_author_preview_overrides, only
+    # once an image/prompt is really built — never in --list-missing mode and
+    # not for files whose preview already exists (keeps listing output clean and
+    # skips wasted YAML-parser subprocesses).
+    # -------------------------------------------------------------------------
+    local IMAGE_STYLE="$IMAGE_STYLE"
+    local IMAGE_STYLE_MODIFIERS="$IMAGE_STYLE_MODIFIERS"
+    local IMAGE_SIZE="$IMAGE_SIZE"
+    local IMAGE_QUALITY="$IMAGE_QUALITY"
+    local IMAGE_MODEL="$IMAGE_MODEL"
+
     # =========================================================================
     # ENHANCE MODE: improve an existing preview image
     # =========================================================================
@@ -1010,7 +1108,10 @@ process_file() {
         
         info "Enhancing preview for: $title"
         debug "Source image: $existing_image ($(du -h "$existing_image" | cut -f1))"
-        
+
+        # Apply the author's art style (if any) before building the prompt
+        apply_author_preview_overrides "$author"
+
         # Build enhancement prompt
         local enhance_prompt
         enhance_prompt=$(build_enhance_prompt "$title" "$description" "$ENHANCE_PROMPT")
@@ -1085,10 +1186,13 @@ process_file() {
     # Preview path should NOT include /assets/ prefix since the template adds it
     local preview_path="/images/previews/${safe_filename}.png"
     
+    # Apply the author's art style (if any) before building the prompt
+    apply_author_preview_overrides "$author"
+
     # Extract content for prompt generation
     local content
     content=$(extract_content "$file")
-    
+
     # Generate prompt
     local prompt
     prompt=$(generate_prompt "$title" "$description" "$categories" "$content")

data/scripts/features/pixelate-preview-images

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+#
+# Script Name: pixelate-preview-images
+# Description: Pixelate + palette-quantize the Jekyll preview banners so they are
+#              much smaller files while retaining the retro pixel-art quality.
+#              Thin, conventions-friendly wrapper around the dependency-free
+#              Python engine in scripts/features/pixelate_images.py.
+#
+# Usage: ./scripts/features/pixelate-preview-images [OPTIONS] [PATHS...]
+#
+#   With no PATHS, the configured preview_images.output_dir from _config.yml is
+#   processed (default: assets/images/previews).
+#
+# Options (wrapper):
+#   -h, --help              Show this help
+#   -v, --version           Print version
+#
+# Options (forwarded to the engine — see --help for the full list):
+#   -n, --dry-run           Report savings without writing
+#   --colors N              Palette size 2-256 (default: 256)
+#   --bits N                Colour precision 1-8 used while quantizing (default: 6)
+#   --max-width N           Downscale so width <= N (default: 1024)
+#   --scale F               Scale factor, e.g. 0.5
+#   --block N               Pixel block size (chunky NxN pixels)
+#   --filter nearest|box    Downsample filter (default: nearest)
+#   --upscale               Restore original WxH (chunky pixels) instead of reduced size
+#   --backup                Keep <file>.orig when writing in place
+#   --force                 Write even if the result is not smaller
+#   -j, --jobs N            Parallel worker processes (default: 1)
+#
+# Examples:
+#   # Preview the savings for every preview banner (no changes):
+#   ./scripts/features/pixelate-preview-images --dry-run -j 4
+#
+#   # Optimize all preview banners in place, 4 workers:
+#   ./scripts/features/pixelate-preview-images -j 4
+#
+#   # Optimize a single image with a chunkier pixel-art look:
+#   ./scripts/features/pixelate-preview-images --block 6 --colors 64 \
+#       assets/images/previews/about.png
+#
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+ENGINE="$SCRIPT_DIR/pixelate_images.py"
+VERSION="1.0.0"
+
+# Source shared logging helpers, with a minimal fallback.
+if [[ -f "$PROJECT_ROOT/scripts/lib/common.sh" ]]; then
+    # shellcheck source=../lib/common.sh
+    source "$PROJECT_ROOT/scripts/lib/common.sh"
+else
+    info()    { echo "[INFO] $1"; }
+    success() { echo "[SUCCESS] $1"; }
+    warn()    { echo "[WARNING] $1" >&2; }
+    error()   { echo "[ERROR] $1" >&2; exit 1; }
+    print_header() { echo "== $1 =="; }
+fi
+
+usage() {
+    sed -n '2,49p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    echo ""
+    echo "Full engine options:"
+    python3 "$ENGINE" --help 2>/dev/null | sed -n '/^options:/,$p' | sed 's/^/  /'
+}
+
+# Resolve preview_images.output_dir from _config.yml (best-effort grep).
+default_output_dir() {
+    local config="$PROJECT_ROOT/_config.yml"
+    local dir=""
+    if [[ -f "$config" ]]; then
+        dir="$(awk '
+            /^preview_images:/ { in_section=1; next }
+            in_section && /^[a-zA-Z_]+:/ { exit }
+            in_section && /output_dir/ {
+                sub(/.*output_dir[[:space:]]*:[[:space:]]*/, "")
+                gsub(/["\x27]/, ""); sub(/[[:space:]]*#.*/, "")
+                print; exit
+            }
+        ' "$config")"
+    fi
+    echo "${dir:-assets/images/previews}"
+}
+
+main() {
+    # Split off wrapper-only flags; forward everything else to the engine.
+    local forward=()
+    local arg
+    for arg in "$@"; do
+        case "$arg" in
+            -h|--help)    usage; exit 0 ;;
+            -v|--version) echo "$VERSION"; exit 0 ;;
+            *)            forward+=("$arg") ;;
+        esac
+    done
+
+    if ! command -v python3 >/dev/null 2>&1; then
+        error "python3 is required but was not found on PATH"
+    fi
+    if [[ ! -f "$ENGINE" ]]; then
+        error "Engine not found: $ENGINE"
+    fi
+
+    # If the caller did not name any existing path, default to the previews dir.
+    local has_path=false a
+    for a in ${forward[@]+"${forward[@]}"}; do
+        if [[ -e "$a" || -e "$PROJECT_ROOT/$a" ]]; then
+            has_path=true
+            break
+        fi
+    done
+    if [[ "$has_path" == false ]]; then
+        local dir
+        dir="$(default_output_dir)"
+        forward+=("$PROJECT_ROOT/$dir")
+        info "No path given; defaulting to: $dir"
+    fi
+
+    print_header "🟪 Pixelate Preview Images"
+    python3 "$ENGINE" ${forward[@]+"${forward[@]}"}
+}
+
+main "$@"