jekyll-theme-zer0 1.26.0 → 1.27.0

data/_includes/core/head.html

@@ -19,6 +19,7 @@
   - seo.html: SEO meta tags and Open Graph data
   - google-analytics.html: Google Analytics tracking
   - google-tag-manager-head.html: GTM head section
+  - posthog.html: PostHog product analytics (opt-in via site.posthog.enabled)
   
   Performance Notes:
   - Scripts loaded in head for immediate availability
@@ -93,6 +94,10 @@ window.MathJax = {
      Outputs custom og:image with assets_prefix normalisation and non-Google site verification. -->
 {% include content/seo.html %}
 
+<!-- hreflang alternates for machine-generated translations (no-op when the
+     page has none) — see _data/i18n/manifest.yml + scripts/translate.rb -->
+{% include core/hreflang.html %}
+
 <!-- ========================== -->
 <!-- STRUCTURED DATA MARKUP    -->
 <!-- ========================== -->
@@ -127,6 +132,10 @@ window.MathJax = {
 <!-- Only load in production AND when an ID is configured; the include also guards against dev hostnames -->
 {% if jekyll.environment == "production" and site.google_analytics %}{% include analytics/google-analytics.html %}{% endif %}
 
+<!-- PostHog analytics - Configured via the `posthog:` block in _config.yml -->
+<!-- Only load in production AND when explicitly enabled; the include itself also respects Do Not Track -->
+{% if jekyll.environment == "production" and site.posthog.enabled %}{% include analytics/posthog.html %}{% endif %}
+
 
 <!-- ================================ -->
 <!-- CSS FRAMEWORKS AND LIBRARIES   -->

data/_includes/core/header.html

@@ -41,9 +41,11 @@
 <!-- ================================ -->
 <!-- SKIP TO CONTENT LINK            -->
 <!-- ================================ -->
+<!-- UI strings resolve per page language (core/i18n.html sets `ui`) -->
+{%- include core/i18n.html -%}
 <!-- Accessibility: allows keyboard users to skip navigation -->
 <a href="#main-content" class="visually-hidden-focusable position-absolute top-0 start-0 z-3 m-3 btn btn-primary">
-  Skip to main content
+  {{ ui.skip_main_content | default: "Skip to main content" }}
 </a>
 
 <header id="navbar" class="container-fluid text-center fixed-top" role="banner">
@@ -149,17 +151,20 @@
             <!-- UTILITY CONTROLS          -->
             <!-- ========================== -->
             <div class="navbar-utility-controls d-flex align-items-center flex-shrink-0" role="group" aria-label="Utility controls">
+                <!-- Language Toggle (renders only when translation.languages is set) -->
+                {% include components/language-toggle.html %}
+
                 <!-- Search Modal Toggle -->
                 <button
                     class="btn nav-search-button"
                     type="button"
                     data-search-toggle
-                    aria-label="Open search"
+                    aria-label="{{ ui.shortcuts_search | default: 'Open search' }}"
                     aria-haspopup="dialog"
-                    title="Search site content"
+                    title="{{ ui.search_button_label | default: 'Search' }}"
                 >
                     <i class="{{site.default_icon}} bi-search" aria-hidden="true"></i>
-                    <span class="nav-link-text d-none d-xl-inline ms-1">Search</span>
+                    <span class="nav-link-text d-none d-xl-inline ms-1">{{ ui.search_button_label | default: "Search" }}</span>
                 </button>
 
                 <!-- Settings Offcanvas Toggle -->

data/_includes/core/hreflang.html

@@ -0,0 +1,33 @@
+{% comment %} Feature: ZER0-078 {% endcomment %}
+{%- comment -%}
+  Component:   hreflang
+  Path:        _includes/core/hreflang.html
+  Purpose:     Emit <link rel="alternate" hreflang> tags for pages that have
+               machine-generated translations, so search engines associate
+               the English original with its /fr/ (etc.) alternates.
+  Params:      none — reads page.lang / page.translation_source_url and the
+               generated _data/i18n/manifest.yml (scripts/translate.rb).
+  Depends on:  site.translation.* config, site.data.i18n.manifest
+  Notes:       Renders nothing when translation is disabled, the manifest is
+               absent, or the current page has no translations. x-default
+               always points at the English original.
+{%- endcomment -%}
+{%- if site.translation.enabled -%}
+  {%- assign _hl_source = site.translation.source_lang | default: 'en' -%}
+  {%- if page.lang and page.lang != _hl_source -%}
+    {%- assign _hl_src_url = page.translation_source_url -%}
+  {%- else -%}
+    {%- assign _hl_src_url = page.url -%}
+  {%- endif -%}
+  {%- assign _hl_entry = site.data.i18n.manifest.pages[_hl_src_url] -%}
+  {%- if _hl_src_url and _hl_entry %}
+<link rel="alternate" hreflang="{{ _hl_source }}" href="{{ _hl_src_url | absolute_url }}">
+    {%- for _hl_lang in site.translation.languages -%}
+      {%- assign _hl_t = _hl_entry[_hl_lang] -%}
+      {%- if _hl_t %}
+<link rel="alternate" hreflang="{{ _hl_lang }}" href="{{ _hl_t.url | absolute_url }}">
+      {%- endif -%}
+    {%- endfor %}
+<link rel="alternate" hreflang="x-default" href="{{ _hl_src_url | absolute_url }}">
+  {%- endif -%}
+{%- endif -%}

data/_includes/core/i18n.html

@@ -0,0 +1,36 @@
+{% comment %} Feature: ZER0-078 {% endcomment %}
+{%- comment -%}
+  Component:   i18n
+  Path:        _includes/core/i18n.html
+  Purpose:     Resolve the active UI-string set into the `ui` variable,
+               per-page-language aware. English strings come from
+               _data/ui-text.yml (the human-maintained source of truth);
+               alternate languages come from _data/i18n/<lang>.yml, which is
+               GENERATED by scripts/translate.rb — never hand-edited.
+  Params:      lang (string, optional) — overrides page.lang. REQUIRED when
+               the caller is rendered via {% include_cached %} (pass
+               lang=page.lang there) so each language gets its own cache
+               entry instead of sharing one page-invariant render.
+  Depends on:  _data/ui-text.yml, _data/i18n/<lang>.yml (generated),
+               site.translation.* config
+  Notes:       Liquid assigns made inside an include are visible to the
+               caller, so after {% include core/i18n.html %} simply use
+               {{ ui.some_key | default: "English fallback" }}. Missing
+               languages or keys degrade to English/literal defaults.
+{%- endcomment -%}
+{%- comment -%}
+  Resolve using the FULL configured language code (e.g. "fr", "pt-BR"), not a
+  2-char slice: scripts/translate.rb writes _data/i18n/<code>.yml and sets
+  page.lang to that exact code, so a regional code like "pt-BR" must look up
+  site.data.i18n["pt-BR"] — slicing to "pt" would silently miss the file and
+  fall back to English.
+{%- endcomment -%}
+{%- assign _i18n_lang = include.lang | default: page.lang | default: site.translation.source_lang | default: site.locale | default: 'en' -%}
+{%- assign _i18n_source = site.translation.source_lang | default: 'en' -%}
+{%- assign ui = site.data.ui-text[site.locale] | default: site.data.ui-text.en -%}
+{%- unless _i18n_lang == _i18n_source -%}
+  {%- assign _i18n_generated = site.data.i18n[_i18n_lang] -%}
+  {%- if _i18n_generated -%}
+    {%- assign ui = _i18n_generated -%}
+  {%- endif -%}
+{%- endunless -%}

data/_includes/navigation/breadcrumbs.html

@@ -14,7 +14,7 @@
   ===================================================================
 {%- endcomment -%}
 {% if page.url != "/" and site.breadcrumbs %}
-  {%- assign ui = site.data.ui-text[site.locale] | default: site.data.ui-text.en -%}
+  {%- include core/i18n.html -%}
   {%- assign label_root = ui.breadcrumbs_root | default: "Home" -%}
   {%- assign label_aria = ui.breadcrumbs_aria | default: "Breadcrumb" -%}
   {%- assign crumbs = page.url | remove:'/index.html' | split: '/' -%}

data/_includes/navigation/navbar.html

@@ -8,11 +8,12 @@
  -->
 
 <!-- Navigation Links - Responsive Offcanvas (inline at lg+, offcanvas below) -->
+{%- include core/i18n.html -%}
 <div class="offcanvas-lg offcanvas-end" tabindex="-1" id="bdNavbar" aria-labelledby="mainNavOffcanvasLabel">
 
     <!-- Main Navigation Header - Offcanvas -->
     <div class="offcanvas-header border-bottom">
-        <h2 class="offcanvas-title h5 mb-0" id="mainNavOffcanvasLabel">Main Navigation</h2>
+        <h2 class="offcanvas-title h5 mb-0" id="mainNavOffcanvasLabel">{{ ui.main_nav_label | default: "Main Navigation" }}</h2>
         <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close navigation menu" data-bs-target="#bdNavbar"></button>
     </div>
 
@@ -24,7 +25,7 @@
             <li class="nav-item d-lg-none">
                 <a class="nav-link" href="{{ '/' | relative_url }}" {% if page.url == '/' %}aria-current="page"{% endif %}>
                     <i class="{{site.default_icon}} bi-house" aria-hidden="true"></i>
-                    Home
+                    {{ ui.home_label | default: "Home" }}
                 </a>
             </li>
             {%- comment -%}
@@ -143,7 +144,7 @@
                     aria-haspopup="dialog"
                 >
                     <i class="{{site.default_icon}} bi-search" aria-hidden="true"></i>
-                    Search
+                    {{ ui.search_button_label | default: "Search" }}
                 </button>
             </li>
             <li class="nav-item d-lg-none">
@@ -156,7 +157,7 @@
                     aria-haspopup="dialog"
                 >
                     <i class="{{site.default_icon}} bi-gear" aria-hidden="true"></i>
-                    Settings
+                    {{ ui.settings_button_label | default: "Settings" }}
                 </button>
             </li>
         </ul>

data/_includes/navigation/sidebar-right.html

@@ -5,6 +5,7 @@
   includes: nav_list.html, content/toc.html
 -->
 
+{%- include core/i18n.html -%}
 <!-- FOUC guard: apply hidden TOC preference before paint -->
 <script>
   try {
@@ -17,7 +18,7 @@
 <!-- Right sidebar container -->
 <div class="offcanvas-lg offcanvas-end" tabindex="-1" id="tocContents" aria-labelledby="tocLabel">
   <div class="offcanvas-header">
-    <h2 class="offcanvas-title h5 mb-0" id="tocLabel">Table of Contents</h2>
+    <h2 class="offcanvas-title h5 mb-0" id="tocLabel">{{ ui.toc_title | default: "Table of Contents" }}</h2>
     <div class="d-flex align-items-center gap-1">
       <button type="button"
               class="btn btn-sm btn-link text-body-secondary bd-toc-visibility-toggle d-lg-none px-2"
@@ -37,7 +38,7 @@
       <div class="mb-3 d-flex align-items-center justify-content-between gap-2">
         <strong class="d-flex align-items-center mb-0">
           <i class="bi bi-file-text me-2" aria-hidden="true"></i>
-          On this page
+          {{ ui.toc_label | default: "On this page" }}
         </strong>
         <button type="button"
                 class="btn btn-sm btn-link text-body-secondary bd-toc-visibility-toggle d-none d-lg-inline-flex flex-shrink-0 px-1"

data/_includes/navigation/unified-drawer.html

@@ -23,7 +23,7 @@
   ===================================================================
 {%- endcomment -%}
 {% if site.navigation.unified_mobile_drawer %}
-{%- assign ui = site.data.ui-text[site.locale] | default: site.data.ui-text.en -%}
+{%- include core/i18n.html -%}
 <div class="offcanvas offcanvas-start zer0-unified-drawer d-lg-none"
      tabindex="-1"
      id="zer0UnifiedDrawer"

data/_layouts/article.html

@@ -15,6 +15,9 @@ layout: default
   Front Matter Variables:
   - post_type: Article type (standard, featured, breaking, opinion, review, tutorial, listicle, interview)
   - sidebar: Override sidebar visibility (true/false)
+  - show_hero: Opt into the top-of-article hero image (page.preview) for any
+    post_type without changing layout/sidebar/badges (true; featured and
+    breaking posts show the hero automatically)
   
   Post Type Variations:
   - standard (default): Normal article with sidebar
@@ -221,12 +224,15 @@ layout: default
     preview image is set. Breaking stories were previously skipped because the
     condition checked only post_type == "featured"; since breaking is mapped
     before featured (see top of file), breaking+featured posts showed no hero.
+    Any other post type can opt in with `show_hero: true` in front matter —
+    this flips only the hero, leaving sidebar, typography, and badges at their
+    post_type defaults (issue #303).
     Nested ifs keep the "only when page.preview exists" guard intact (Liquid has
     no parentheses, so a flat `a or b and c` would misgroup).
   {% endcomment %}
   {% assign show_hero = false %}
   {% if page.preview %}
-    {% if post_type == "featured" or post_type == "breaking" %}
+    {% if post_type == "featured" or post_type == "breaking" or page.show_hero %}
       {% assign show_hero = true %}
     {% endif %}
   {% endif %}

data/_layouts/default.html

@@ -86,8 +86,10 @@ layout: root
     <!-- ================================ -->
     <!-- MAIN CONTENT AREA               -->
     <!-- ================================ -->
-    <!-- Primary content section with scroll spy for table of contents navigation -->
-    <main class="bd-main order-1" data-bs-spy="scroll" data-bs-target="#TableOfContents" data-bs-offset="100" data-bs-smooth-scroll="true">
+    <!-- Primary content section with scroll spy for table of contents navigation.
+         Not a <main>: root.html already provides the single <main id="main-content">
+         landmark; a nested <main> here would duplicate it (issue #299). -->
+    <div class="bd-main order-1" data-bs-spy="scroll" data-bs-target="#TableOfContents" data-bs-offset="100" data-bs-smooth-scroll="true">
 
         {%- comment -%}
           Page introduction: title, breadcrumbs, metadata.
@@ -129,5 +131,5 @@ layout: root
               {% include content/backlinks.html %}
             {% endif %}
         </div>
-      </main>
+      </div>
     </div>

data/_layouts/news.html

@@ -78,7 +78,9 @@ source: "https://getbootstrap.com/docs/5.3/examples/blog/#"
   </div>
 </div>
 
-<main class="container">
+<!-- Not a <main>: root.html already provides the single <main id="main-content">
+     landmark; a nested <main> here would duplicate it (issue #299). -->
+<div class="container">
 
 {% if section_style == "magazine" %}
   <!-- ================================ -->
@@ -578,7 +580,7 @@ source: "https://getbootstrap.com/docs/5.3/examples/blog/#"
     </div>
   </section>
 
-</main>
+</div>
 
 <style>
   .hover-lift {

data/_layouts/root.html

@@ -46,7 +46,7 @@
 {%- else -%}
   {%- assign _bs_theme = 'dark' -%}
 {%- endif -%}
-<html lang="{{ site.locale | slice: 0,2 | default: 'en' }}" class="no-js" data-bs-theme="{{ _bs_theme }}" data-color-mode-default="{{ _cm }}" data-theme-skin="{{ site.theme_skin | default: 'dark' }}" data-zer0-bg="{{ site.theme_background.enabled | default: true }}">
+<html lang="{{ page.lang | default: site.locale | slice: 0, 2 | default: 'en' }}" class="no-js" data-bs-theme="{{ _bs_theme }}" data-color-mode-default="{{ _cm }}" data-theme-skin="{{ site.theme_skin | default: 'dark' }}" data-zer0-bg="{{ site.theme_background.enabled | default: true }}">
     <head>
         <!-- =============================================== -->
         <!-- HEAD SECTION: Meta tags, styles, and SEO setup -->
@@ -82,11 +82,13 @@
              Enable with `navigation.unified_mobile_drawer: true` in _config.yml. -->
         {% include navigation/unified-drawer.html %}
 
-        <!-- Search modal (site-wide) — page-invariant, cached once per build. -->
-        {% include_cached components/search-modal.html %}
+        <!-- Search modal (site-wide) — cached once per build PER LANGUAGE
+             (the lang param keys the include-cache entry; page.lang is nil
+             on English pages, so they all still share a single render). -->
+        {% include_cached components/search-modal.html lang=page.lang %}
 
-        <!-- Keyboard shortcuts help modal (triggered by `?`) — page-invariant. -->
-        {% include_cached components/shortcuts-modal.html %}
+        <!-- Keyboard shortcuts help modal (triggered by `?`) — cached per language. -->
+        {% include_cached components/shortcuts-modal.html lang=page.lang %}
 
         <!-- Settings offcanvas (Appearance / Site / Developer tabs) -->
         {% include components/info-section.html %}
@@ -98,10 +100,14 @@
         <!-- MAIN CONTENT AREA        -->
         <!-- ======================== -->
         <!-- Skip-link target: keep a single, consistent #main-content anchor site-wide.
-             Semantic <main> landmark (consistent with the default/section/news layouts)
-             so assistive tech, search engines, and AI content extractors can isolate the
+             This is the ONE <main> landmark per page — child layouts (default/section/
+             news) must use non-landmark wrappers (<div>) inside it (issue #299) — so
+             assistive tech, search engines, and AI content extractors can isolate the
              primary content from the surrounding header/nav/footer chrome. -->
         <main id="main-content">
+            <!-- Machine-translation disclosure — renders only on generated
+                 translations (page.machine_translated); no-op elsewhere. -->
+            {%- include components/translation-notice.html -%}
             {{ content }}
         </main>
 
@@ -116,7 +122,7 @@
              fresh: jekyll-include-cache stores in memory only (Jekyll 3.x has no
              Jekyll::Cache) and clears on every build's :pre_render hook — it never
              persists to .jekyll-cache. -->
-        {%- include_cached core/footer.html -%}
+        {%- include_cached core/footer.html lang=page.lang -%}
         {%- include core/footer-fabs.html -%}
 
         <!-- Privacy-compliant cookie consent banner — page-invariant. -->

data/_layouts/section.html

@@ -156,7 +156,9 @@ layout: root
     <!-- ================================ -->
     <!-- MAIN CONTENT AREA                -->
     <!-- ================================ -->
-    <main class="col-lg-9 col-xl-10 section-layout-main">
+    <!-- Not a <main>: root.html already provides the single <main id="main-content">
+         landmark; a nested <main> here would duplicate it (issue #299). -->
+    <div class="col-lg-9 col-xl-10 section-layout-main">
       
       <!-- Section Header -->
       <header class="section-header mb-4">
@@ -526,7 +528,7 @@ layout: root
         </div>
       </aside>
 
-    </main>
+    </div>
   </div>
 </div>
 

data/_sass/core/_obsidian.scss

@@ -208,11 +208,19 @@
 // in _sass/theme/_backgrounds.scss (specificity 0,5,0) and forces
 // `position: relative; z-index: 1` — dropping the FAB into page flow at the
 // bottom. An id (1,0,0) wins, mirroring `#aiChatToggle`. See ai-chat.html.
+//
+// Slot 2 on the left-side FAB stack: sits above the page-feedback FAB
+// (slot 1 = var(--zer0-space-fab-offset)) — same stacking formula as
+// .bd-toc-fab above #backToTopBtn on the right side.
 #obsidianLocalGraphFab.obsidian-local-graph-fab {
   position: fixed;
   left: var(--zer0-space-fab-offset, 1rem);
   right: auto;
-  bottom: var(--zer0-space-fab-offset, 1rem);
+  bottom: calc(
+    var(--zer0-space-fab-offset, 1rem) +
+    var(--zer0-space-fab-size, 3.5rem) +
+    var(--zer0-space-fab-gap, 0.75rem)
+  );
   z-index: var(--zer0-layer-fab-local-graph);
 
   &[hidden] {

data/_sass/layouts/_navbar-extras.scss

@@ -80,7 +80,12 @@
   &.bd-sidebar-fab--restore,
   html.bd-sidebar-pref-hidden &.bd-sidebar-fab {
     display: block !important;
-    bottom: var(--zer0-space-fab-offset, 1rem);
+    // Stay at slot 2 (above the feedback FAB at slot 1) so neither overlaps.
+    bottom: calc(
+      var(--zer0-space-fab-offset, 1rem) +
+      var(--zer0-space-fab-size, 3.5rem) +
+      var(--zer0-space-fab-gap, 0.75rem)
+    );
   }
 
   @media (min-width: 992px) {

data/assets/js/obsidian-graph.js

@@ -28,7 +28,11 @@
   'use strict';
 
   var CONTAINER_ID = 'obsidian-graph';
-  var INDEX_URL = (window.OBSIDIAN_WIKI_INDEX_URL ||
+  // Index URL resolution mirrors obsidian-wiki-links.js: the baseurl-aware
+  // value js-cdn.html emits (OBSIDIAN_CONFIG.wikiIndexUrl), then the legacy
+  // per-page override global, then a <base>-relative fallback.
+  var INDEX_URL = ((window.OBSIDIAN_CONFIG || {}).wikiIndexUrl ||
+    window.OBSIDIAN_WIKI_INDEX_URL ||
     ((document.querySelector('base') || {}).href || '/') + 'assets/data/wiki-index.json');
 
   function normalize(value) {

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);
+});