jekyll-theme-zer0 1.26.0 → 1.28.0

data/assets/js/obsidian-local-graph.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-045
 /*
  * obsidian-local-graph.js
  *
@@ -12,8 +13,13 @@
  * Subgraph:
  *   - center  = current page (matched against entry.url, falling back to
  *               normalized title/basename/aliases for permalink quirks)
- *   - depth   = configurable via data-depth attribute (default 1)
- *   - direction = both incoming and outgoing wiki-links
+ *   - depth   = 1–3, user-adjustable in the panel (default from the
+ *               data-depth attribute / `local_graph_depth` front matter)
+ *   - direction = outgoing and/or incoming wiki-links, user-toggleable
+ *
+ * Depth + direction preferences persist to localStorage
+ * (zer0.obsidianLocalGraph.v1) and the graph re-renders in place when they
+ * change — same for Bootstrap color-mode (data-bs-theme) switches.
  *
  * If the current page is in the wiki-index but has no local links, the panel
  * stays available and renders a single-node graph for the current page.
@@ -26,6 +32,7 @@
   var PANEL_SELECTOR = '[data-obsidian-local-graph-panel]';
   var TOGGLE_SELECTOR = '[data-obsidian-local-graph-toggle]';
   var STATUS_SELECTOR = '[data-obsidian-local-graph-status]';
+  var STORAGE_KEY = 'zer0.obsidianLocalGraph.v1';
 
   // Cytoscape is vendored under assets/vendor/ (no runtime CDN — matches the
   // Bootstrap / Icons / Mermaid policy). The path is supplied by Liquid via
@@ -57,6 +64,28 @@
       .replace(/"/g, '"').replace(/'/g, ''');
   }
 
+  // Depth + direction preferences. Depth falls back to the page's data-depth
+  // (front-matter `local_graph_depth`), directions default to both on.
+  function loadPrefs(defaultDepth) {
+    var prefs = { depth: defaultDepth, outgoing: true, incoming: true };
+    try {
+      var saved = JSON.parse(window.localStorage.getItem(STORAGE_KEY) || 'null');
+      if (saved && typeof saved === 'object') {
+        var d = parseInt(saved.depth, 10);
+        if (d >= 1 && d <= 3) prefs.depth = d;
+        if (typeof saved.outgoing === 'boolean') prefs.outgoing = saved.outgoing;
+        if (typeof saved.incoming === 'boolean') prefs.incoming = saved.incoming;
+      }
+    } catch (e) { /* private mode / corrupt payload — use defaults */ }
+    return prefs;
+  }
+
+  function savePrefs(prefs) {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
+    } catch (e) { /* storage unavailable — prefs are session-only */ }
+  }
+
   function companionElements(container) {
     return {
       panel: container.closest(PANEL_SELECTOR),
@@ -143,10 +172,11 @@
     return palette[name] || '#6c757d';
   }
 
-  // BFS from the current entry up to `depth` hops, following both
-  // outgoing edges and incoming edges (any other entry whose `outgoing`
-  // includes one of our keys).
-  function buildSubgraph(entries, lookup, current, depth) {
+  // BFS from the current entry up to `depth` hops. Directions are opt-in:
+  // opts.outgoing follows this page's [[links]], opts.incoming follows any
+  // other entry whose `outgoing` includes one of our keys.
+  function buildSubgraph(entries, lookup, current, depth, opts) {
+    opts = opts || { outgoing: true, incoming: true };
     var visited = Object.create(null);
     var queue = [{ entry: current, dist: 0 }];
     var nodes = [];
@@ -206,45 +236,49 @@
       if (item.dist >= depth) continue;
 
       // Outgoing edges
-      (entry.outgoing || []).forEach(function (target) {
-        var nk = normalize(target);
-        var resolved = lookup.byKey[nk];
-        if (resolved) {
-          if (resolved.url === entry.url) return;
-          addEdge(entry.url, resolved.url, false);
-          if (!visited[resolved.url]) {
-            queue.push({ entry: resolved, dist: item.dist + 1 });
+      if (opts.outgoing) {
+        (entry.outgoing || []).forEach(function (target) {
+          var nk = normalize(target);
+          var resolved = lookup.byKey[nk];
+          if (resolved) {
+            if (resolved.url === entry.url) return;
+            addEdge(entry.url, resolved.url, false);
+            if (!visited[resolved.url]) {
+              queue.push({ entry: resolved, dist: item.dist + 1 });
+            }
+          } else {
+            var brokenId = '__broken__:' + nk;
+            if (!visited[brokenId]) {
+              visited[brokenId] = true;
+              nodes.push({
+                group: 'nodes',
+                data: {
+                  id: brokenId,
+                  label: target,
+                  url: null,
+                  collection: 'broken',
+                  color: '#dc3545',
+                  broken: true
+                }
+              });
+            }
+            addEdge(entry.url, brokenId, true);
           }
-        } else {
-          var brokenId = '__broken__:' + nk;
-          if (!visited[brokenId]) {
-            visited[brokenId] = true;
-            nodes.push({
-              group: 'nodes',
-              data: {
-                id: brokenId,
-                label: target,
-                url: null,
-                collection: 'broken',
-                color: '#dc3545',
-                broken: true
-              }
-            });
-          }
-          addEdge(entry.url, brokenId, true);
-        }
-      });
+        });
+      }
 
       // Incoming edges (anyone whose outgoing matches one of our keys)
-      keysFor(entry).forEach(function (k) {
-        (reverse[k] || []).forEach(function (src) {
-          if (src.url === entry.url) return;
-          addEdge(src.url, entry.url, false);
-          if (!visited[src.url]) {
-            queue.push({ entry: src, dist: item.dist + 1 });
-          }
+      if (opts.incoming) {
+        keysFor(entry).forEach(function (k) {
+          (reverse[k] || []).forEach(function (src) {
+            if (src.url === entry.url) return;
+            addEdge(src.url, entry.url, false);
+            if (!visited[src.url]) {
+              queue.push({ entry: src, dist: item.dist + 1 });
+            }
+          });
         });
-      });
+      }
     }
 
     return nodes.concat(edges);
@@ -299,6 +333,11 @@
   }
 
   function render(container, elements, currentUrl) {
+    // Re-renders (depth/direction/theme changes) replace the prior instance.
+    if (container.__obsidianLocalGraph) {
+      try { container.__obsidianLocalGraph.destroy(); } catch (e) { /* ignore */ }
+      container.__obsidianLocalGraph = null;
+    }
     var theme = readTheme();
     container.style.backgroundColor = theme.canvasBg;
     var motion = prefersReducedMotion() ? '0ms' : '160ms';
@@ -460,6 +499,59 @@
     return nav;
   }
 
+  // Reflect prefs into the depth radio group + direction switches.
+  function syncControls(prefs) {
+    var radio = document.getElementById('obsidian-lg-depth-' + prefs.depth);
+    if (radio) radio.checked = true;
+    var outgoing = document.getElementById('obsidian-lg-outgoing');
+    if (outgoing) outgoing.checked = prefs.outgoing;
+    var incoming = document.getElementById('obsidian-lg-incoming');
+    if (incoming) incoming.checked = prefs.incoming;
+  }
+
+  function wireControls(prefs, rebuild) {
+    [1, 2, 3].forEach(function (d) {
+      var radio = document.getElementById('obsidian-lg-depth-' + d);
+      if (!radio) return;
+      radio.addEventListener('change', function () {
+        if (!radio.checked) return;
+        prefs.depth = d;
+        savePrefs(prefs);
+        rebuild();
+      });
+    });
+    var outgoing = document.getElementById('obsidian-lg-outgoing');
+    if (outgoing) {
+      outgoing.addEventListener('change', function () {
+        prefs.outgoing = outgoing.checked;
+        savePrefs(prefs);
+        rebuild();
+      });
+    }
+    var incoming = document.getElementById('obsidian-lg-incoming');
+    if (incoming) {
+      incoming.addEventListener('change', function () {
+        prefs.incoming = incoming.checked;
+        savePrefs(prefs);
+        rebuild();
+      });
+    }
+  }
+
+  // Re-render on Bootstrap color-mode changes so canvas colors track the
+  // theme without a reload. Local graphs are small — a full rebuild is cheap.
+  function watchTheme(rebuild) {
+    var restyle = debounce(rebuild, 60);
+    var observer = new MutationObserver(restyle);
+    [document.documentElement, document.body].forEach(function (el) {
+      observer.observe(el, { attributes: true, attributeFilter: ['data-bs-theme'] });
+    });
+    if (window.matchMedia) {
+      var mq = window.matchMedia('(prefers-color-scheme: dark)');
+      if (mq.addEventListener) mq.addEventListener('change', restyle);
+    }
+  }
+
   function init() {
     var container = document.getElementById(CONTAINER_ID);
     if (!container) return;
@@ -478,8 +570,9 @@
       resizeGraph(container);
     }, 150));
 
-    var depth = parseInt(container.getAttribute('data-depth') || '1', 10);
-    if (!isFinite(depth) || depth < 1) depth = 1;
+    var defaultDepth = parseInt(container.getAttribute('data-depth') || '1', 10);
+    if (!isFinite(defaultDepth) || defaultDepth < 1) defaultDepth = 1;
+    var prefs = loadPrefs(Math.min(defaultDepth, 3));
     var indexUrl = container.getAttribute('data-index-url') ||
       ((document.querySelector('base') || {}).href || '/') +
       'assets/data/wiki-index.json';
@@ -496,17 +589,21 @@
         // Confirmed in-index: reveal the panel + FAB now.
         setPanelAvailable(container, true);
         setStatus(container, 'Loading graph…', false);
-
-        var elements = buildSubgraph(entries, lookup, current, depth);
-        var nodeCount = elements.filter(function (element) { return element.group === 'nodes'; }).length;
-        var edgeCount = elements.filter(function (element) { return element.group === 'edges'; }).length;
-        // Accessible text fallback (also the graceful degradation if cytoscape
-        // can't load): a list of linked neighbours below the canvas.
-        var fallback = renderTextFallback(container, elements, current);
-
-        loadCytoscape(function (ok) {
-          if (ok === false) {
-            // Keep the text list visible; hide the empty canvas.
+        syncControls(prefs);
+
+        var graphAvailable = null; // unknown until loadCytoscape resolves
+
+        function rebuild() {
+          var elements = buildSubgraph(entries, lookup, current, prefs.depth, {
+            outgoing: prefs.outgoing,
+            incoming: prefs.incoming
+          });
+          var nodeCount = elements.filter(function (el) { return el.group === 'nodes'; }).length;
+          var edgeCount = elements.filter(function (el) { return el.group === 'edges'; }).length;
+          // Accessible text fallback (also the graceful degradation if
+          // cytoscape can't load): a list of linked neighbours below the canvas.
+          var fallback = renderTextFallback(container, elements, current);
+          if (graphAvailable === false) {
             container.hidden = true;
             setStatus(container, 'Showing linked pages (interactive graph unavailable).', false);
             return;
@@ -515,6 +612,16 @@
           setStatus(container, nodeCount + ' pages · ' + edgeCount + ' links', false);
           // Graph is the visual representation; keep the list for AT only.
           if (fallback) fallback.classList.add('visually-hidden');
+        }
+
+        wireControls(prefs, rebuild);
+        watchTheme(function () {
+          if (container.__obsidianLocalGraph) rebuild();
+        });
+
+        loadCytoscape(function (ok) {
+          graphAvailable = ok !== false;
+          rebuild();
         });
       })
       .catch(function (err) {

data/assets/js/search-modal.js

@@ -74,8 +74,11 @@
             if (typeof bootstrap === 'undefined') return;
             const cookieEl = document.getElementById('cookieSettingsModal');
             const infoEl = document.getElementById('info-section');
+            const drawerEl = document.getElementById('zer0UnifiedDrawer');
             afterModalClosed(cookieEl, () => {
-                afterOffcanvasClosed(infoEl, showSearchModal);
+                afterOffcanvasClosed(infoEl, () => {
+                    afterOffcanvasClosed(drawerEl, showSearchModal);
+                });
             });
         };
 

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

@@ -35,12 +35,15 @@ DESCRIPTION:
     Run automatically by scripts/bin/release before tagging.
 
 OPTIONS:
+    --check         Exit non-zero if the committed manifest is stale; write
+                    nothing. `generated_at` is ignored in the comparison.
     --dry-run       Print manifest to stdout; don't write the file
     --verbose       Show each file being processed
     --help, -h      Show this help message
 
 EXAMPLES:
     ./scripts/bin/manifest                  # Regenerate _data/theme-manifest.yml
+    ./scripts/bin/manifest --check          # CI gate: is the manifest current?
     ./scripts/bin/manifest --dry-run        # Preview output
     ./scripts/bin/manifest --verbose        # Show every file being hashed
 EOF
@@ -67,7 +70,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"
 )
 
@@ -82,9 +84,11 @@ OPTIONAL_PLUGIN_PATHS=(
 # Argument parsing
 DRY_RUN=false
 VERBOSE=false
+CHECK=false
 
 while [[ $# -gt 0 ]]; do
     case $1 in
+        --check)     CHECK=true; DRY_RUN=true ;;
         --dry-run)   DRY_RUN=true ;;
         --verbose)   VERBOSE=true ;;
         --help|-h)   show_usage; exit 0 ;;
@@ -94,7 +98,14 @@ while [[ $# -gt 0 ]]; do
 done
 
 # ---------------------------------------------------------------------------
-step "Generating theme manifest..."
+# Under --dry-run stdout carries only the manifest YAML — the CI freshness gate
+# (ci.yml "Theme manifest freshness") diffs that stdout straight against the
+# committed file, so progress logs must not pollute it.
+if [[ "$DRY_RUN" == "true" ]]; then
+    step "Generating theme manifest..." >&2
+else
+    step "Generating theme manifest..."
+fi
 cd "$REPO_ROOT"
 
 CURRENT_VERSION=$(get_current_version)
@@ -174,10 +185,25 @@ YAML
 )
 
 # ---------------------------------------------------------------------------
-if [[ "$DRY_RUN" == "true" ]]; then
-    info "[DRY RUN] Would write _data/theme-manifest.yml:"
+MANIFEST_FILE="$REPO_ROOT/_data/theme-manifest.yml"
+
+if [[ "$CHECK" == "true" ]]; then
+    # Staleness = any difference other than the generation timestamp, which moves
+    # on every run and would otherwise report a false positive every time.
+    if [[ ! -f "$MANIFEST_FILE" ]]; then
+        error "Manifest missing: _data/theme-manifest.yml — run ./scripts/bin/manifest"
+    fi
+    if diff -u \
+        <(grep -v '^generated_at:' "$MANIFEST_FILE") \
+        <(echo "$MANIFEST_CONTENT" | grep -v '^generated_at:') >&2; then
+        success "Manifest is current (version $CURRENT_VERSION)" >&2
+        exit 0
+    fi
+    error "Manifest is stale — run ./scripts/bin/manifest and commit the result"
+elif [[ "$DRY_RUN" == "true" ]]; then
+    info "[DRY RUN] Would write _data/theme-manifest.yml:" >&2
     echo "$MANIFEST_CONTENT"
 else
-    echo "$MANIFEST_CONTENT" > "$REPO_ROOT/_data/theme-manifest.yml"
+    echo "$MANIFEST_CONTENT" > "$MANIFEST_FILE"
     success "Written: _data/theme-manifest.yml (version $CURRENT_VERSION)"
 fi

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/bin/validate

@@ -391,7 +391,11 @@ if File.file?('_config_secrets_local.yml')
   assert(!tracked, '_config_secrets_local.yml must remain untracked and ignored')
 end
 
-ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache test/fixtures]
+# examples/ holds self-contained demo sites, each with its own _config.yml and
+# _config_dev.yml. Those belong to the example, not to this site's config
+# surface, so prune the tree rather than registering every example's configs in
+# classified_files below (which would need editing for each new example).
+ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache test/fixtures examples]
 config_like_files = []
 
 Find.find('.') do |path|

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