jekyll-theme-zer0 1.25.0 → 1.27.0

data/scripts/README.md

@@ -18,7 +18,7 @@ scripts/
 │   ├── git.sh             # Git operations
 │   ├── changelog.sh       # Changelog generation
 │   ├── gem.sh             # Gem build/publish
-│   └── preview_generator.py  # Python preview image generator
+│   └── preview_generator.py  # Preview-image engine (Claude orchestrates; ZER0-004)
 ├── features/              # Feature-specific scripts
 │   ├── generate-preview-images     # AI preview image generator
 │   ├── pixelate-preview-images     # Shrink preview banners (pixelate + PNG-8)
@@ -65,10 +65,7 @@ Build the gem without the full release workflow.
 ```
 
 #### `bin/validate`
-Run preflight validation before refactors, pull requests, and releases. The
-quick path validates repository files, version consistency, YAML parsing, active
-configuration contracts, config-file classification, and navigation data before
-the Docker/local build stages run.
+Run preflight validation before refactors, pull requests, and releases. The quick path validates repository files, version consistency, YAML parsing, active configuration contracts, config-file classification, and navigation data before the Docker/local build stages run.
 
 ```bash
 ./scripts/bin/validate [options]
@@ -115,22 +112,23 @@ Options:
   --dry-run           Preview without changes
   --collection TYPE   Generate for specific collection (posts, docs, etc.)
   -f, --file PATH     Process specific file
-  --provider PROVIDER Use specific AI provider (openai, stability, xai)
+  --provider PROVIDER Renderer (openai, xai, stability, gemini, local)
+  --prompt-engine ENG claude analyzes the article (default) | template
+  --review ENG        claude reviews the render (default) | none
   --assets-prefix     Custom assets path prefix (default: /assets)
   --no-auto-prefix    Disable automatic path prefixing
 
-AI Providers:
-  openai    - OpenAI DALL-E (requires OPENAI_API_KEY)
-  stability - Stability AI (requires STABILITY_API_KEY)
+Renderers (Claude orchestrates all of them — analysis + review via
+CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY / logged-in `claude` CLI):
+  openai    - OpenAI gpt-image-2 / DALL-E, default (requires OPENAI_API_KEY)
   xai       - xAI Grok image generation (requires XAI_API_KEY)
+  stability - Stability AI (requires STABILITY_API_KEY)
+  gemini    - Google Gemini (requires GEMINI_API_KEY)
+  local     - Deterministic template SVG/PNG (no 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).
+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:
@@ -157,10 +155,7 @@ Options (forwarded to scripts/features/pixelate_images.py):
   -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`.
+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.
@@ -254,7 +249,7 @@ These are sourced by other scripts, not executed directly:
 - `git.sh` - Git operations (tags, commits, branches)
 - `changelog.sh` - Changelog generation from commits
 - `gem.sh` - Gem build/publish operations
-- `preview_generator.py` - Python preview image generator
+- `preview_generator.py` - Preview-image engine (Claude analyze/review + openai/xai/stability/gemini/local renderers)
 
 ### Test Suites (scripts/test/)
 
@@ -272,8 +267,7 @@ These are sourced by other scripts, not executed directly:
 
 ## Backward Compatibility
 
-Legacy script paths (e.g., `./scripts/build.sh`) are maintained as thin wrappers
-that forward to the canonical locations in `bin/`, `utils/`, `features/`, or `test/`.
+Legacy script paths (e.g., `./scripts/build.sh`) are maintained as thin wrappers that forward to the canonical locations in `bin/`, `utils/`, `features/`, or `test/`.
 
 ## Development Workflow
 
@@ -538,15 +532,15 @@ The script is designed to integrate with AI agents for automated content managem
 3. **Front Matter Updates**: Automatically updates the markdown file with the new preview path
 4. **Idempotent**: Won't regenerate images that already exist (unless `--force`)
 
-### Python Alternative
+### Engine
 
-A Python version is available at `scripts/lib/preview_generator.py` with additional features:
+All logic lives in the single-file Python engine `scripts/lib/preview_generator.py` (the shell entry points are thin wrappers around it):
 
 ```bash
-# Install dependencies
-pip install openai pyyaml requests
+# Install the one dependency
+pip3 install pyyaml
 
-# Run Python version
+# Run the engine directly (same flags as the wrapper)
 python3 scripts/lib/preview_generator.py --collection posts --dry-run
 ```
 

data/scripts/bin/audit-consumer

@@ -190,7 +190,7 @@ if [[ ${#THEMABLE_DIRS[@]} -eq 0 ]]; then
     THEMABLE_DIRS=("_layouts" "_includes" "_sass" "assets/css" "assets/js")
 fi
 if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]]; then
-    REQUIRED_PLUGIN_FILES=("_plugins/preview_image_generator.rb" "_plugins/obsidian_links.rb")
+    REQUIRED_PLUGIN_FILES=("_plugins/obsidian_links.rb")
     OPTIONAL_PLUGIN_FILES=("_plugins/admin_page_urls.rb" "_plugins/content_statistics_generator.rb" "_plugins/theme_version.rb")
 fi
 

data/scripts/bin/manifest

@@ -67,7 +67,6 @@ THEME_DATA_PATHS=(
 # Plugins that remote_theme consumers MUST vendor locally (GitHub Pages won't
 # load plugins from a remote theme).
 REQUIRED_PLUGIN_PATHS=(
-    "_plugins/preview_image_generator.rb"
     "_plugins/obsidian_links.rb"
 )
 

data/scripts/bin/sync-plugins

@@ -172,7 +172,6 @@ fi
 # Default hardcoded fallback if manifest has no plugin entries at all
 if [[ ${#REQUIRED_PLUGINS[@]} -eq 0 && ${#OPTIONAL_PLUGINS[@]} -eq 0 ]]; then
     REQUIRED_PLUGINS=(
-        "_plugins/preview_image_generator.rb"
         "_plugins/obsidian_links.rb"
     )
     OPTIONAL_PLUGINS=(

data/scripts/dev/rasterize-svg.js

@@ -0,0 +1,65 @@
+// Feature: ZER0-004
+// SVG → PNG rasterizer for the preview-image engine (scripts/lib/preview_generator.py).
+// Last resort in the rasterizer chain (rsvg-convert → inkscape → magick → THIS):
+// uses the repo's Playwright devDependency (the same Chromium that powers the
+// visual test tiers) so contributors need no native image tooling installed.
+//
+// Usage:
+//   node scripts/dev/rasterize-svg.js <in.svg> <out.png> [width] [height]
+//
+// Exit codes:
+//   0  PNG written
+//   1  rasterization failed (Chromium error, unreadable SVG, …)
+//   2  usage error
+//   3  @playwright/test not resolvable (caller should fall through / keep .svg)
+const fs = require('fs');
+const path = require('path');
+
+const [svgPath, pngPath, widthArg, heightArg] = process.argv.slice(2);
+if (!svgPath || !pngPath) {
+  console.error('Usage: node scripts/dev/rasterize-svg.js <in.svg> <out.png> [width] [height]');
+  process.exit(2);
+}
+const width = parseInt(widthArg, 10) || 1536;
+const height = parseInt(heightArg, 10) || 1024;
+
+let chromium;
+try {
+  ({ chromium } = require('@playwright/test'));
+} catch (e) {
+  console.error('rasterize-svg: @playwright/test not resolvable from ' + process.cwd());
+  process.exit(3);
+}
+
+(async () => {
+  const svg = fs.readFileSync(path.resolve(svgPath), 'utf8');
+  const browser = await chromium.launch();
+  try {
+    const ctx = await browser.newContext({
+      viewport: { width, height },
+      deviceScaleFactor: 1,
+    });
+    // Defense-in-depth: banner SVG must be self-contained, so block ALL
+    // network fetches — an external reference that slipped past the engine's
+    // sanitizer becomes a no-op instead of an SSRF/tracking request.
+    await ctx.route('**/*', (route) => route.abort());
+    const page = await ctx.newPage();
+    // Inline the SVG in a zero-margin shim and stretch it to the viewport so the
+    // screenshot is exactly width×height regardless of the SVG's own attributes.
+    await page.setContent(
+      `<!DOCTYPE html><html><head><style>
+         html,body{margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden;background:#000}
+         svg{display:block;width:${width}px;height:${height}px}
+       </style></head><body>${svg}</body></html>`,
+      { waitUntil: 'load', timeout: 30000 }
+    );
+    await page.screenshot({ path: path.resolve(pngPath), fullPage: false });
+    await ctx.close();
+    console.log('wrote', pngPath);
+  } finally {
+    await browser.close();
+  }
+})().catch((err) => {
+  console.error('rasterize-svg: ' + (err && err.message ? err.message : err));
+  process.exit(1);
+});