jekyll-theme-zer0 1.30.0 → 1.31.0

data/assets/js/mermaid-diagrams.js

@@ -12,10 +12,21 @@
  *          that keeps the diagram source on the page instead of losing it.
  *
  * Loaded by _includes/components/mermaid.html — only on pages that opt in
- * with `mermaid: true` — after the vendored mermaid.min.js. Both scripts
- * are `defer`, so this runs once the DOM is parsed but BEFORE
- * DOMContentLoaded: fences are converted before code-copy.js decorates
- * <pre> blocks, so a diagram never gets a copy button and a line gutter.
+ * with `mermaid: true`. The script is `defer`, so it runs once the DOM is
+ * parsed but BEFORE DOMContentLoaded: fences are converted before
+ * code-copy.js decorates <pre> blocks, so a diagram never gets a copy button
+ * and a line gutter.
+ *
+ * Lazy loading
+ *   The Mermaid bundle (~1 MB minified) is NOT loaded by the include. This
+ *   file converts the fences into figures (skeleton + toolbar) straight away,
+ *   then injects the bundle only when the page really has a diagram AND the
+ *   first one comes within LAZY_MARGIN of the viewport (IntersectionObserver).
+ *   A `mermaid: true` page with no fences never downloads it, and a diagram
+ *   far below the fold no longer costs the first paint. Once loaded, every
+ *   figure renders. The bundle URL comes from window.zer0MermaidSrc (set by
+ *   the include from site.mermaid.src). If a consumer still loads
+ *   mermaid.min.js itself, the existing global is used and nothing is injected.
  *
  * Reads one JSON block injected by the include:
  *   #mermaidConfig — securityLevel, toolbar/fullscreen/download flags, labels
@@ -36,6 +47,7 @@
  *   mermaid.render(), so a theme switch re-renders from the original text.
  *
  * Public API (also what the Playwright spec drives):
+ *   window.zer0Mermaid.load()            -> Promise<mermaid>   load the bundle now (no-op once loaded)
  *   window.zer0Mermaid.renderAll(root?)  -> Promise<figure[]>  convert + render fences under root
  *   window.zer0Mermaid.render(el, src?)  -> Promise<figure>    render one element (or replace it with src)
  *   window.zer0Mermaid.refresh()         -> Promise<figure[]>  re-derive the palette, re-render every figure
@@ -94,6 +106,32 @@
   var SUPPORTS_DIALOG = typeof HTMLDialogElement !== "undefined" &&
     typeof HTMLDialogElement.prototype.showModal === "function";
 
+  // How far below (or above) the viewport a diagram may be before the
+  // Mermaid bundle is fetched — enough lead time that a reader scrolling at a
+  // normal pace finds it rendered.
+  var LAZY_MARGIN = "400px 0px";
+
+  // Bundle URL: the include sets window.zer0MermaidSrc from site.mermaid.src
+  // (default /assets/vendor/mermaid/mermaid.min.js) through relative_url. It
+  // is a script global, not DOM text, because it ends up in script.src.
+  // Fallback for an overridden include that doesn't set it: the vendored path
+  // next to this file. Only http(s) URLs are ever injected.
+  var SELF_SRC = (document.currentScript && document.currentScript.src) || "";
+  var MERMAID_SRC = safeScriptUrl(
+    (typeof window.zer0MermaidSrc === "string" && window.zer0MermaidSrc) ||
+    (SELF_SRC ? SELF_SRC.replace(/js\/mermaid-diagrams\.js(\?.*)?$/, "vendor/mermaid/mermaid.min.js") : "")
+  );
+
+  function safeScriptUrl(raw) {
+    if (!raw) return "";
+    try {
+      var u = new URL(raw, document.baseURI);
+      return (u.protocol === "https:" || u.protocol === "http:") ? u.href : "";
+    } catch (e) {
+      return "";
+    }
+  }
+
   var ZOOM_MIN = 0.5;
   var ZOOM_MAX = 4;
   var ZOOM_STEP = 1.25;
@@ -322,10 +360,11 @@
 
     var ink = tokenColor("--bs-body-color", dark ? "#dee2e6" : "#212529", bgRgb);
     var inkMuted = tokenColor("--bs-secondary-color", dark ? "#adb5bd" : "#6c757d", bgRgb);
-    // The skin mixin writes both --bs-primary and --zer0-color-primary, but a
-    // site-level `theme_color.main` re-pins the latter at :root after main.css,
-    // so only --bs-primary reliably follows the active skin — it is what the
-    // buttons and links the reader sees are painted with.
+    // Under a palette skin --bs-primary and --zer0-color-primary now agree
+    // (T-048: the skin beats `theme_color`). They still differ under the
+    // dark/contrast skins, where `theme_color.main` sets only the theme token.
+    // --bs-primary stays first because the buttons and links the reader sees
+    // are painted with it.
     var primary = tokenColor("--bs-primary", "var(--zer0-color-primary, #007bff)", bgRgb);
     var accent = tokenColor("--zer0-color-accent", "#ffe484", bgRgb);
     // Keep the brand usable as a border/line colour on this background.
@@ -1185,7 +1224,11 @@
     refreshTimer = setTimeout(function () { refresh(false); }, 80);
   }
 
+  var themeWatched = false;
+
   function watchTheme() {
+    if (themeWatched) return;
+    themeWatched = true;
     if (typeof MutationObserver === "function") {
       var observer = new MutationObserver(scheduleRefresh);
       // `style` catches the Appearance panel writing token overrides onto
@@ -1203,19 +1246,77 @@
     }
   }
 
+  // ---------------------------------------------------------------------
+  // Lazy bundle loading
+  // ---------------------------------------------------------------------
+  var mermaidPromise = null;
+
+  function mermaidReady() {
+    return !!(window.mermaid && typeof window.mermaid.render === "function");
+  }
+
+  function markUnavailable() {
+    // Vendor bundle missing: leave the fences as readable code blocks.
+    document.documentElement.classList.add("zer0-diagram-unavailable");
+    if (window.console && console.warn) console.warn("[zer0-mermaid] mermaid.min.js did not load; diagrams left as source.");
+  }
+
+  // Inject the Mermaid bundle once; every caller shares the same promise.
+  function loadMermaid() {
+    if (mermaidReady()) return Promise.resolve(window.mermaid);
+    if (mermaidPromise) return mermaidPromise;
+    mermaidPromise = new Promise(function (resolve, reject) {
+      if (!MERMAID_SRC) { reject(new Error("no Mermaid bundle URL")); return; }
+      var script = document.createElement("script");
+      script.src = MERMAID_SRC;
+      script.async = true;
+      script.setAttribute("data-zer0-mermaid", "");
+      script.onload = function () {
+        if (mermaidReady()) resolve(window.mermaid);
+        else reject(new Error("mermaid global missing after load"));
+      };
+      script.onerror = function () { reject(new Error("failed to load " + MERMAID_SRC)); };
+      document.head.appendChild(script);
+    });
+    mermaidPromise.catch(function () { mermaidPromise = null; });
+    return mermaidPromise;
+  }
+
+  // Resolve when the first of `figures` is within LAZY_MARGIN of the viewport.
+  function whenNearViewport(figures) {
+    return new Promise(function (resolve) {
+      if (typeof window.IntersectionObserver !== "function") { resolve(); return; }
+      var io = new IntersectionObserver(function (entries) {
+        if (entries.some(function (e) { return e.isIntersecting; })) {
+          io.disconnect();
+          resolve();
+        }
+      }, { rootMargin: LAZY_MARGIN });
+      figures.forEach(function (f) { io.observe(f); });
+    });
+  }
+
   // ---------------------------------------------------------------------
   // Public API + boot
   // ---------------------------------------------------------------------
   function renderAll(root) {
-    if (!window.mermaid) return Promise.resolve([]);
-    initMermaid(false);
-    var figures = collect(root || document);
-    return renderMany(figures);
+    return loadMermaid().then(function () {
+      initMermaid(false);
+      watchTheme();
+      var figures = collect(root || document);
+      return renderMany(figures);
+    }, function () { return []; });
   }
 
   function render(target, source) {
-    if (!window.mermaid) return Promise.resolve(null);
+    return loadMermaid().then(function () {
+      return renderOne(target, source);
+    }, function () { return null; });
+  }
+
+  function renderOne(target, source) {
     initMermaid(false);
+    watchTheme();
     var figure;
     if (target && registry.has(target)) {
       figure = target;
@@ -1237,9 +1338,10 @@
   }
 
   window.zer0Mermaid = {
-    version: "3.0.0",
+    version: "3.1.0",
     config: CONFIG,
     labels: LABELS,
+    load: loadMermaid,
     renderAll: renderAll,
     render: render,
     refresh: function () { return refresh(true); },
@@ -1252,14 +1354,18 @@
   };
 
   function boot() {
-    if (!window.mermaid || typeof window.mermaid.render !== "function") {
-      // Vendor bundle missing: leave the fences as readable code blocks.
-      document.documentElement.classList.add("zer0-diagram-unavailable");
-      if (window.console && console.warn) console.warn("[zer0-mermaid] mermaid.min.js did not load; diagrams left as source.");
-      return;
-    }
-    renderAll(document);
-    watchTheme();
+    // Fences become figures (skeleton + toolbar) now; Mermaid is not needed
+    // for that. No diagram on the page → the bundle is never requested.
+    var figures = collect(document);
+    if (!figures.length) return;
+    var start = mermaidReady() ? Promise.resolve() : whenNearViewport(figures);
+    start
+      .then(loadMermaid)
+      .then(function () {
+        initMermaid(false);
+        watchTheme();
+        return renderMany(allFigures.filter(function (f) { return f.isConnected; }));
+      }, markUnavailable);
   }
 
   if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot);

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

@@ -8,7 +8,11 @@
  *
  * Loaded by _includes/navigation/local-graph.html inside a dedicated
  * collapsible side panel. Cytoscape.js is loaded lazily (and only once) from
- * the vendored copy under assets/vendor/cytoscape/ (no CDN).
+ * the vendored copy under assets/vendor/cytoscape/ (no CDN), and only when
+ * the panel is first opened: the panel is a closed offcanvas on page load, so
+ * fetching ~118 KB of cytoscape for a graph nobody has asked to see was pure
+ * main-thread cost on every indexed page. Until then the accessible
+ * text list of linked pages is kept up to date.
  *
  * Subgraph:
  *   - center  = current page (matched against entry.url, falling back to
@@ -592,6 +596,7 @@
         syncControls(prefs);
 
         var graphAvailable = null; // unknown until loadCytoscape resolves
+        var graphRequested = false;
 
         function rebuild() {
           var elements = buildSubgraph(entries, lookup, current, prefs.depth, {
@@ -603,6 +608,11 @@
           // 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 === null) {
+            // Panel not opened yet: cytoscape is not loaded, keep the list.
+            setStatus(container, nodeCount + ' pages · ' + edgeCount + ' links', false);
+            return;
+          }
           if (graphAvailable === false) {
             container.hidden = true;
             setStatus(container, 'Showing linked pages (interactive graph unavailable).', false);
@@ -619,10 +629,22 @@
           if (container.__obsidianLocalGraph) rebuild();
         });
 
-        loadCytoscape(function (ok) {
-          graphAvailable = ok !== false;
-          rebuild();
-        });
+        function requestGraph() {
+          if (graphRequested) return;
+          graphRequested = true;
+          setStatus(container, 'Loading graph…', false);
+          loadCytoscape(function (ok) {
+            graphAvailable = ok !== false;
+            rebuild();
+          });
+        }
+
+        rebuild(); // text list + counts, no cytoscape yet
+        if (!panel || panel.classList.contains('show')) {
+          requestGraph();
+        } else {
+          panel.addEventListener('show.bs.offcanvas', requestGraph);
+        }
       })
       .catch(function (err) {
         // Sidebar panel failing is non-fatal — keep it hidden and stay quiet.

data/assets/js/setup-wizard.js

@@ -1981,10 +1981,15 @@
     return data;
   }
 
+  // `is-visible` is the ONLY handle on the chip's appearance. It used to also
+  // clear `hidden`, which the 2s timer below never restored (that timer only
+  // drops `is-visible`, an opacity/visibility class) — so the first debounced
+  // save moved the chip into layout permanently and shifted the whole wizard
+  // down 7px (issue #265). _setup-wizard.scss reserves the box and hides it
+  // with `visibility`, so there is nothing here to toggle but the class.
   function showDraftChip() {
     var chip = document.getElementById('wizard-draft-chip');
     if (!chip) return;
-    chip.hidden = false;
     chip.classList.add('is-visible');
     clearTimeout(chipTimer);
     chipTimer = setTimeout(function () { chip.classList.remove('is-visible'); }, 2000);
@@ -2016,7 +2021,7 @@
     draftTimer = null;
     try { localStorage.removeItem(DRAFT_KEY); } catch (e) { /* ignore */ }
     var chip = document.getElementById('wizard-draft-chip');
-    if (chip) { chip.classList.remove('is-visible'); chip.hidden = true; }
+    if (chip) { chip.classList.remove('is-visible'); }
   }
 
   function restoreDraft() {

data/scripts/ci/test_visual_evidence_autogen.py

@@ -192,6 +192,25 @@ def test_parse_results() -> None:
           f.get("diff") == "test/visual-results/output/a/homepage-sunrise-diff.png")
 
 
+def test_parse_results_playwright_158_attachment_names() -> None:
+    print("parse_playwright_results — Playwright 1.58+ names attachments with their extension")
+    results = {"suites": [{"title": "appearance-snapshot.spec.js", "suites": [{"title": "Theme skins", "suites": [
+        {"title": "skin: air", "specs": [{"title": "homepage visual snapshot", "tests": [{"results": [
+            {"status": "failed", "error": {"message": "2009 pixels (ratio 0.01 of all image pixels) are different."},
+             "attachments": [
+                 {"name": "homepage-air-expected.png", "path": "/work/test/visual-results/output/a/homepage-air-expected.png"},
+                 {"name": "homepage-air-actual.png", "path": "/work/test/visual-results/output/a/homepage-air-actual.png"},
+                 {"name": "homepage-air-diff.png", "path": "/work/test/visual-results/output/a/homepage-air-diff.png"}]}]}]}]},
+    ]}]}]}
+    parsed = vea.parse_playwright_results(results)
+    f = parsed["failures"][0] if parsed["failures"] else {}
+    check("skin taken from the describe title", f.get("skin") == "air")
+    check("pixel count parsed", f.get("diff_px") == 2009)
+    check("expected resolved despite the .png suffix", f.get("expected") is not None)
+    check("actual resolved despite the .png suffix", f.get("actual") is not None)
+    check("diff resolved despite the .png suffix", f.get("diff") is not None)
+
+
 def test_decide() -> None:
     print("decide — only `intentional` on a failing verify may bless")
     fail = {"snapshots": {"verified": "fail"}}
@@ -259,6 +278,47 @@ def test_stage_command_output() -> None:
         check("one path per line when there is something to add", buf.getvalue() == "test/visual/evidence/x\n")
 
 
+def test_generic_generator_survives_livereload() -> None:
+    """Run 36932006025 (#495): pr-evidence.mjs died at its third width with
+    "page.$: Execution context was destroyed" and wrote no metrics or PNGs.
+
+    The jammy run's `npm ci` created node_modules/ AFTER `jekyll serve --watch`
+    started; jekyll-watch ignores only the `exclude:` paths that exist when it
+    starts, so Jekyll regenerated and LiveReload reloaded the open page mid-shot.
+    Pinned from both ends: the watcher must ignore node_modules/, and the
+    generator must neither listen to LiveReload nor let one shot end the sweep.
+    """
+    print("generic generator — a mid-sweep LiveReload never aborts the sweep")
+    src = (REPO_ROOT / vea.GENERIC_GENERATOR).read_text(encoding="utf-8")
+    check("pr-evidence.mjs aborts the injected livereload.js",
+          re.search(r"const LIVERELOAD_URL_RE = /.*livereload", src) is not None
+          and "page.route(LIVERELOAD_URL_RE, (r) => r.abort())" in src)
+    unguarded = [ln.strip() for ln in src.splitlines()
+                 if re.search(r"await page\.(\$|\$\$|evaluate)\(", ln) and ".catch(" not in ln]
+    check(f"every page-context call in pr-evidence.mjs is guarded ({unguarded or 'none unguarded'})",
+          not unguarded)
+
+    import contextlib
+    import io
+    import os
+    import tempfile
+    calls: list[tuple[str, bool]] = []
+    real_run, real_http_ok, cwd = vea.run, vea.http_ok, os.getcwd()
+    with tempfile.TemporaryDirectory() as tmp:
+        try:
+            os.chdir(tmp)
+            vea.http_ok = lambda url, timeout=3.0: any(c[0].startswith("docker compose up") for c in calls)
+            vea.run = lambda cmd, **kw: calls.append((" ".join(cmd), Path("node_modules").is_dir()))
+            with contextlib.redirect_stdout(io.StringIO()):
+                vea.ensure_jekyll(timeout=5)
+        finally:
+            vea.run, vea.http_ok = real_run, real_http_ok
+            os.chdir(cwd)
+    up = [had for cmd, had in calls if cmd.startswith("docker compose up")]
+    check("ensure_jekyll creates node_modules/ BEFORE `docker compose up` (so the watcher ignores it)",
+          up == [True])
+
+
 def test_lane_tooling_contract() -> None:
     """The regression that killed the lane's first real run on a real PR.
 
@@ -328,8 +388,10 @@ def test_workflow_wiring() -> None:
 def main() -> int:
     for t in (test_detect_slug, test_plan_pr_454_shape, test_plan_loop_guard_and_budget, test_plan_generic_fallback,
               test_plan_respects_author_evidence, test_plan_out_of_scope, test_styling_matches_ci_filter,
-              test_ui_prefixes_match_gate, test_parse_results, test_decide, test_stage_and_messages,
-              test_stage_command_output, test_lane_tooling_contract, test_workflow_wiring):
+              test_ui_prefixes_match_gate, test_parse_results, test_parse_results_playwright_158_attachment_names,
+              test_decide, test_stage_and_messages,
+              test_stage_command_output, test_generic_generator_survives_livereload,
+              test_lane_tooling_contract, test_workflow_wiring):
         t()
     print(f"\n{PASSED} passed, {len(FAILURES)} failed")
     for f in FAILURES:

data/scripts/ci/visual_evidence_autogen.py

@@ -400,13 +400,18 @@ def parse_playwright_results(results: dict) -> dict:
                 m = re.search(r"(\d+) pixels", message)
                 exp = act = dif = None
                 for name, p in attachments.items():
-                    if name.endswith("-expected"):
+                    # Playwright 1.58 names screenshot attachments with their
+                    # file extension (e.g. "homepage-air-expected.png"); older
+                    # versions did not. Strip it before matching the suffix so
+                    # both forms resolve to the same three roles.
+                    stem = re.sub(r"\.(png|jpe?g)$", "", name)
+                    if stem.endswith("-expected"):
                         exp = rel_path(p)
-                    elif name.endswith("-actual"):
+                    elif stem.endswith("-actual"):
                         act = rel_path(p)
-                    elif name.endswith("-diff"):
+                    elif stem.endswith("-diff"):
                         dif = rel_path(p)
-                        skin = skin or name[: -len("-diff")].replace("homepage-", "")
+                        skin = skin or stem[: -len("-diff")].replace("homepage-", "")
                 failures.append({
                     "skin": skin or spec.get("title", "?"),
                     "status": status,
@@ -447,6 +452,11 @@ def ensure_jekyll(timeout: int) -> bool:
     if http_ok(HEAD_URL + "/"):
         log(f"Jekyll already serving {HEAD_URL} — reusing it.")
         return False
+    # jekyll-watch ignores only the `exclude:` paths that EXIST when its watcher
+    # starts. On a fresh checkout node_modules/ does not, so the jammy run's
+    # `npm ci` would set off a regeneration whose LiveReload reloads every open
+    # page mid-shot (the pr-evidence.mjs crash on #495). Create it first.
+    Path("node_modules").mkdir(exist_ok=True)
     log("Starting Jekyll via docker compose…")
     run(["docker", "compose", "up", "-d"], capture=False)
     log(f"Waiting up to {timeout}s for {HEAD_URL} (cold bundle install + first build)…")

data/scripts/features/install-preview-generator

@@ -262,7 +262,7 @@ update_config() {
 preview_images:
   enabled: true
   provider: ${DEFAULT_PROVIDER}          # renderer: openai, xai, stability, gemini, local
-  model: ""                              # empty = renderer default (gpt-image-2, grok-2-image, ...)
+  model: ""                              # empty = renderer default (gpt-image-2, grok-imagine-image-2.0, ...)
   size: "1536x1024"                      # Landscape banner size
   quality: auto                          # auto for GPT Image; standard/hd for DALL-E 3
   style: "retro pixel art, 8-bit video game aesthetic, vibrant colors, nostalgic, clean pixel graphics"

data/scripts/lib/README.md

@@ -153,6 +153,18 @@ publish_gem "1.2.0"
 create_github_release "1.2.0"
 ```
 
+### 🖼️ `preview_generator.py` - Preview Image Engine
+
+The Python engine behind `scripts/generate-preview-images.sh`. Renderer defaults when `preview_images.model` is empty:
+
+| provider | default model | credential |
+| --- | --- | --- |
+| `openai` (default) | `gpt-image-2` | `OPENAI_API_KEY` |
+| `xai` | `grok-imagine-image-2.0` | `XAI_API_KEY` |
+| `gemini` | `gemini-2.5-flash-image` | `GEMINI_API_KEY` |
+
+Unit specs: `python3 test/test_preview_generator.py`.
+
 ## Testing
 
 Each library has comprehensive unit tests in `scripts/test/lib/`.

data/scripts/lib/preview_generator.py

@@ -24,7 +24,7 @@ Architecture — Claude ORCHESTRATES, an image model RENDERS:
     --------   --------------------------------------   ----------------------------------
     openai     gpt-image-2 / dall-e-3 (+ --enhance      OPENAI_API_KEY
     (default)  via /v1/images/edits)
-    xai        grok-2-image                             XAI_API_KEY
+    xai        grok-imagine-image-2.0                   XAI_API_KEY
     stability  Stable Diffusion XL (v1 API)             STABILITY_API_KEY
     gemini     gemini-2.5-flash-image                   GEMINI_API_KEY
     local      deterministic template SVG → PNG         none (CI-safe; skips
@@ -1688,7 +1688,7 @@ class XAIProvider(Provider):
         return "XAI_API_KEY environment variable is required for the xAI provider"
 
     def default_model(self) -> str:
-        return "grok-2-image"
+        return "grok-imagine-image-2.0"
 
     def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
         model = effective_model(settings, self)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.30.0
+  version: 1.31.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -345,6 +345,7 @@ files:
 - _sass/utilities/_layout.scss
 - _sass/utilities/_motion.scss
 - assets/css/custom.css
+- assets/css/extension-points-demo.css
 - assets/css/main.scss
 - assets/css/stats.css
 - assets/css/theme-npm-entry.scss
@@ -362,6 +363,7 @@ files:
 - assets/js/code-copy.js
 - assets/js/config-utility.js
 - assets/js/docs.min.js
+- assets/js/extension-points-demo.js
 - assets/js/fleet-feedback-capture.js
 - assets/js/fleet-feedback.js
 - assets/js/halfmoon.js