jekyll-theme-zer0 1.31.1 → 1.31.3

data/_includes/core/favicon.html

@@ -10,7 +10,7 @@
   Params:      none — reads the optional `favicon:` block in _config.yml:
 
                favicon:
-                 ico         : /favicon.ico                    # legacy .ico (default)
+                 ico         : /favicon.ico                    # legacy .ico (always emitted when set)
                  svg         : /assets/images/favicon.svg      # scalable icon (optional)
                  png         : /assets/images/favicon-32.png   # PNG icon (optional)
                  png_size    : 32x32                           # sizes attr for png (optional)
@@ -20,9 +20,13 @@
                  theme_color_light : "#ffffff"                 # light-scheme chrome (optional)
                  theme_color_dark  : "#212529"                 # dark-scheme chrome (optional)
 
-               With NO config at all this still emits the explicit
-               /favicon.ico link (every consumer site carries one at root)
-               AND both theme-color tags. That last part is the point of the
+               With NO `favicon.ico` configured, the default icon link is
+               emitted only for a root icon file that actually exists in
+               site.static_files: /favicon.ico, else /favicon.png, else
+               /favicon.svg — and nothing at all when none exists. A
+               remote_theme consumer does not get this repo's favicon.ico, so
+               an unconditional /favicon.ico link 404'd on every page of such
+               sites (issue #536). Both theme-color tags are always emitted. That last part is the point of the
                fallbacks below: a remote_theme consumer does not inherit this
                repo's _config.yml (see remote-theme-checklist.md), so a
                config-gated tag emitted nothing at all on exactly the sites
@@ -31,8 +35,40 @@
                run through relative_url so baseurl deployments resolve.
 {%- endcomment -%}
 {%- assign _fav = site.favicon -%}
-{%- assign _fav_ico = _fav.ico | default: '/favicon.ico' -%}
-<link rel="icon" href="{{ _fav_ico | relative_url }}" sizes="32x32">
+{%- comment -%}
+  Default icon (issue #536). A configured `favicon.ico` is trusted as-is.
+  Otherwise probe site.static_files (each entry's `path` is source-relative,
+  e.g. "/favicon.ico") for a root icon, in order .ico -> .png -> .svg, and
+  emit a link only for one that exists. The .png/.svg fallbacks are skipped
+  when the same kind is already configured via favicon.png / favicon.svg, so
+  the page never carries two links of one type.
+{%- endcomment -%}
+{%- assign _fav_default = '' -%}
+{%- assign _fav_default_type = '' -%}
+{%- if _fav.ico -%}
+  {%- assign _fav_default = _fav.ico -%}
+{%- else -%}
+  {%- assign _fav_hit = site.static_files | where: "path", "/favicon.ico" | first -%}
+  {%- if _fav_hit -%}
+    {%- assign _fav_default = '/favicon.ico' -%}
+  {%- elsif _fav.png == nil -%}
+    {%- assign _fav_hit = site.static_files | where: "path", "/favicon.png" | first -%}
+    {%- if _fav_hit -%}
+      {%- assign _fav_default = '/favicon.png' -%}
+      {%- assign _fav_default_type = 'image/png' -%}
+    {%- endif -%}
+  {%- endif -%}
+  {%- if _fav_default == '' and _fav.svg == nil -%}
+    {%- assign _fav_hit = site.static_files | where: "path", "/favicon.svg" | first -%}
+    {%- if _fav_hit -%}
+      {%- assign _fav_default = '/favicon.svg' -%}
+      {%- assign _fav_default_type = 'image/svg+xml' -%}
+    {%- endif -%}
+  {%- endif -%}
+{%- endif -%}
+{%- if _fav_default != '' %}
+<link rel="icon"{% if _fav_default_type != '' %} type="{{ _fav_default_type }}"{% endif %} href="{{ _fav_default | relative_url }}"{% if _fav_default_type == '' %} sizes="32x32"{% endif %}>
+{%- endif %}
 {%- if _fav.svg %}
 <link rel="icon" type="image/svg+xml" href="{{ _fav.svg | relative_url }}">
 {%- endif %}

data/_includes/core/footer.html

@@ -40,9 +40,8 @@
   {% assign footer_page_urls = site.html_pages | map: "url" | join: "|" | prepend: "|" | append: "|" %}
   {% comment %} Powered by Row {% endcomment %}
   <div class="container-xl footer-powered-by">
-    <p class="footer-powered-by-copyright text-center mb-0">
-      &copy; {{ site.time | date: "%Y" }} {{ site.name | default: site.title }}
-    </p>
+    {%- comment -%} The copyright line lives once, in the bottom bar below.
+       A second "© year name" line here printed the notice twice (backlog T-054). {%- endcomment -%}
     <div class="footer-powered-by-row">
       <span class="footer-powered-by-label" id="footer-powered-by-label">
         {{ ui.powered_by | default: "Powered by" }}:

data/_includes/core/header.html

@@ -43,8 +43,17 @@
 {% comment %} ================================ {% endcomment %}
 {% comment %} UI strings resolve per page language (core/i18n.html sets `ui`) {% endcomment %}
 {%- include core/i18n.html -%}
-{% comment %} Accessibility: allows keyboard users to skip navigation {% endcomment %}
-<a href="#main-content" class="visually-hidden-focusable position-absolute top-0 start-0 z-3 m-3 btn btn-primary">
+{% comment %} Accessibility: allows keyboard users to skip navigation.
+     Target: `#main-content` (the single <main> in root.html) unless the page or
+     a layout in its chain sets `skip_link_target` in front matter. Layouts with
+     their own navigation inside <main> point it past that chrome, e.g.
+     default.html (docs sidebar + TOC) → `page-content`. Jekyll merges layout
+     front matter up the chain with the innermost layout winning, so a child
+     layout (a site's quest layout, say) can override its parent's target.
+     `.zer0-skip-to-content` lifts it above the fixed-top navbar when focused
+     (_sass/utilities/_focus.scss); `z-3` left it underneath, invisible. {% endcomment %}
+{%- assign skip_link_target = page.skip_link_target | default: layout.skip_link_target | default: "main-content" -%}
+<a href="#{{ skip_link_target }}" class="zer0-skip-to-content visually-hidden-focusable position-absolute top-0 start-0 m-3 btn btn-primary">
   {{ ui.skip_main_content | default: "Skip to main content" }}
 </a>
 

data/_includes/setup/wizard.html

@@ -178,7 +178,7 @@
                 <div class="col-md-6">
                   <label for="sb-model" class="form-label">Model</label>
                   <select class="form-select form-select-sm" id="sb-model" disabled>
-                    <option value="{{ sb_cfg.model | default: site.ai_chat.model | default: 'claude-opus-4-8' }}">{{ sb_cfg.model | default: site.ai_chat.model | default: 'claude-opus-4-8' }}</option>
+                    <option value="{{ sb_cfg.model | default: site.ai_chat.model | default: 'claude-opus-5-5' }}">{{ sb_cfg.model | default: site.ai_chat.model | default: 'claude-opus-5-5' }}</option>
                   </select>
                   <div class="form-text" id="sb-model-note">Sent with every request; the proxy can pin one with <code>CHAT_MODEL</code> / <code>XAI_CHAT_MODEL</code>.</div>
                 </div>
@@ -1021,7 +1021,7 @@
   "endpoint": {{ sb_cfg.endpoint | default: "/api/wizard" | jsonify }},
   "chatEndpoint": {{ sb_cfg.chat_endpoint | default: site.ai_chat.endpoint | default: "/api/chat" | jsonify }},
   "provider": {{ sb_cfg.provider | default: "auto" | jsonify }},
-  "model": {{ sb_cfg.model | default: site.ai_chat.model | default: "claude-opus-4-8" | jsonify }},
+  "model": {{ sb_cfg.model | default: site.ai_chat.model | default: "claude-opus-5-5" | jsonify }},
   "mode": {{ sb_cfg.mode | default: "guided" | jsonify }},
   "imageProvider": {{ sb_cfg.image_provider | default: "" | jsonify }},
   "maxTokens": {{ sb_cfg.max_tokens | default: 8192 }},

data/_layouts/default.html

@@ -1,6 +1,9 @@
 ---
 # Features: ZER0-001, ZER0-008, ZER0-019
 layout: root
+# The skip link (core/header.html) jumps past the docs sidebar, intro and
+# TOC straight to the page body below.
+skip_link_target: page-content
 ---
 {% comment %}
   ===================================================================
@@ -122,7 +125,11 @@ layout: root
         {% comment %} MAIN CONTENT BODY              {% endcomment %}
         {% comment %} =============================== {% endcomment %}
         {% comment %} Where the actual page content is rendered {% endcomment %}
-        <div class="bd-content ps-lg-2">
+        {% comment %} Skip-link target for this layout (see front matter). tabindex="-1"
+             lets the link move keyboard focus here, not just scroll (same reason
+             as #main-content in root.html); its focus ring is suppressed in
+             _sass/utilities/_focus.scss. {% endcomment %}
+        <div id="page-content" class="bd-content ps-lg-2" tabindex="-1">
             {{ content }}
 
             {%- comment -%}

data/_sass/components/_back-to-top.scss

@@ -35,4 +35,13 @@
     background-color: var(--zer0-color-link-hover, var(--bs-primary));
     transform: translateY(-2px);
   }
+
+  // `outline: 0` above removes the UA ring, and the hover-style change alone
+  // was the only focus cue (opacity, a darker fill, a 2px lift), which is not
+  // a visible indicator (WCAG 2.4.7). Same 2px primary ring as the site-wide
+  // :focus-visible rule in utilities/_focus.scss; mouse clicks stay ring-free.
+  &:focus-visible {
+    outline: 2px solid var(--zer0-color-primary, var(--bs-primary));
+    outline-offset: 2px;
+  }
 }

data/_sass/components/_cookie-banner.scss

@@ -86,3 +86,34 @@
     }
   }
 }
+
+// ----------------------------------------------------------------------------
+// Reserve the banner's space while it is up
+// ----------------------------------------------------------------------------
+// components/cookie-consent.html sets `zer0-cookie-banner-open` on <html> and
+// `--zer0-cookie-banner-inset` to the banner's height (kept current by a
+// ResizeObserver) while the banner is shown, and removes both once a choice
+// hides it. Without this the fixed bar covered the end of every page, the
+// floating buttons (Back to top sat fully under it at 1366px), and whatever
+// keyboard focus scrolled to near the bottom edge (WCAG 2.4.11).
+html.zer0-cookie-banner-open {
+  // Focus and anchor scrolling stop above the banner, not under it.
+  scroll-padding-bottom: var(--zer0-cookie-banner-inset, 0px);
+
+  body {
+    // The last content on the page can scroll clear of the banner.
+    padding-bottom: var(--zer0-cookie-banner-inset, 0px);
+  }
+
+  // Lift the floating buttons (both FAB stacks) above the banner. `translate`
+  // composes with the `transform` hover/active lifts these buttons already
+  // use, so it does not fight them.
+  #backToTopBtn,
+  #aiChatToggle,
+  #obsidianLocalGraphFab,
+  .pf-fab,
+  .bd-toc-fab,
+  .bd-sidebar-fab {
+    translate: 0 calc(-1 * var(--zer0-cookie-banner-inset, 0px));
+  }
+}

data/_sass/utilities/_focus.scss

@@ -29,10 +29,21 @@ summary:focus-visible {
 // Safe here specifically because the element is tabindex="-1": it is never
 // reachable by Tab, so no keyboard user can land on it and be left without an
 // indicator. Do not generalise this selector to focusable elements.
-#main-content:focus {
+#main-content:focus,
+#page-content:focus {
   outline: none;
 }
 
+// The header's "Skip to main content" link (core/header.html). Bootstrap's
+// visually-hidden-focusable reveals it on focus, but it sat at `z-3` under the
+// fixed-top navbar (z-index 1030), so a focused skip link was invisible. When
+// focused it is pinned to the viewport above the navbar and the cookie banner.
+.zer0-skip-to-content:focus,
+.zer0-skip-to-content:focus-within {
+  position: fixed !important;
+  z-index: var(--zer0-layer-skip-link, 1100) !important;
+}
+
 // Skip-to-content link — visually hidden until focused
 .zer0-skip-link {
   position: absolute;

data/assets/js/modules/navigation/index.js

@@ -36,6 +36,50 @@ import { TocVisibility } from './toc-visibility.js';
 import { SidebarVisibility } from './sidebar-visibility.js';
 import { Navbar } from './navbar.js';
 
+/** Marker in an init step list: give the main thread back before continuing. */
+const YIELD = Symbol('yield');
+
+/**
+ * Yield to the main thread so pending input and rendering can run.
+ * Uses scheduler.yield() where available (keeps our priority), otherwise a
+ * macrotask via MessageChannel (no 4ms setTimeout clamp).
+ * @returns {Promise<void>}
+ */
+function yieldToMain() {
+    if (typeof window !== 'undefined' && window.scheduler && typeof window.scheduler.yield === 'function') {
+        return window.scheduler.yield();
+    }
+    return new Promise(resolve => {
+        if (typeof MessageChannel === 'function') {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = () => resolve();
+            channel.port2.postMessage(null);
+        } else {
+            setTimeout(resolve, 0);
+        }
+    });
+}
+
+/**
+ * Run init steps in order, yielding at each YIELD marker. A step that throws
+ * is logged and does not stop the steps after it.
+ * @param {Array<Function|symbol>} steps
+ * @returns {Promise<void>}
+ */
+async function runSteps(steps) {
+    for (const step of steps) {
+        if (step === YIELD) {
+            await yieldToMain();
+            continue;
+        }
+        try {
+            step();
+        } catch (error) {
+            console.error('Navigation: Initialization error', error);
+        }
+    }
+}
+
 /**
  * Navigation Controller - Orchestrates all navigation modules
  */
@@ -54,59 +98,69 @@ export class Navigation {
             console.warn('Navigation: Already initialized');
             return this;
         }
+        this._initialized = true;
 
-        try {
+        // Start-up is split across tasks so it never becomes one long task.
+        // Phase 1 (this task) wires the controls a user can reach right away:
+        // sidebar state, keyboard shortcuts, focus management and the navbar.
+        // None of them read layout. Each later step reads styles or layout
+        // (breakpoints, TOC/sidebar visibility, scroll spy), so each one runs
+        // in its own task after yielding to the main thread, letting the
+        // browser paint and handle input in between. `navigation:ready` is
+        // still dispatched once every module exists.
+        const steps = [
+            () => { this.modules.state = new SidebarState(); },
+            () => { this.modules.keyboard = new KeyboardShortcuts(); },
+            () => { this.modules.focus = new FocusManager(); },
+            () => {
+                // Initialize navbar (hover dropdowns, mobile menu, tooltips,
+                // focus trap) — formerly the standalone assets/js/navigation.js IIFE.
+                this.modules.navbar = new Navbar(config);
+                this.modules.navbar.init();
+            },
+            YIELD,
             // Sync breakpoints from --zer0-bp-* CSS custom properties so a fork
             // overriding tokens in SCSS automatically propagates to JS checks.
-            syncBreakpointsFromCss();
-
-            // Initialize sidebar state first (other modules may depend on it)
-            this.modules.state = new SidebarState();
-
-            const leftSidebar = document.querySelector(config.selectors.leftSidebar);
-            const docsLayout = document.querySelector(config.selectors.docsLayout);
-            if (leftSidebar && docsLayout && !docsLayout.classList.contains('bd-layout--no-sidebar')) {
-                this.modules.sidebarVisibility = new SidebarVisibility();
-            }
-            
-            // Initialize TOC-related modules only if TOC exists
-            const toc = document.querySelector(config.selectors.toc);
-            if (toc) {
+            // getComputedStyle forces a full style recalc, so it runs after the
+            // first yield, before the modules that use breakpoints.
+            () => { syncBreakpointsFromCss(); },
+            () => { this.modules.gestures = new SwipeGestures(); },
+            YIELD,
+            () => {
+                const leftSidebar = document.querySelector(config.selectors.leftSidebar);
+                const docsLayout = document.querySelector(config.selectors.docsLayout);
+                if (leftSidebar && docsLayout && !docsLayout.classList.contains('bd-layout--no-sidebar')) {
+                    this.modules.sidebarVisibility = new SidebarVisibility();
+                }
+            },
+            YIELD,
+            () => {
+                // Initialize TOC-related modules only if TOC exists
+                if (!document.querySelector(config.selectors.toc)) {
+                    console.log('Navigation: No TOC found, skipping scroll spy and smooth scroll');
+                    return;
+                }
                 this.modules.tocVisibility = new TocVisibility();
-                this.modules.scrollSpy = new ScrollSpy();
                 this.modules.smoothScroll = new SmoothScroll();
-            } else {
-                console.log('Navigation: No TOC found, skipping scroll spy and smooth scroll');
+            },
+            YIELD,
+            () => {
+                if (!this.modules.tocVisibility) return;
+                // ScrollSpy defers its own first measurement to idle time.
+                this.modules.scrollSpy = new ScrollSpy();
             }
-            
-            // Initialize keyboard shortcuts
-            this.modules.keyboard = new KeyboardShortcuts();
-            
-            // Initialize gesture support
-            this.modules.gestures = new SwipeGestures();
-            
-            // Initialize focus management
-            this.modules.focus = new FocusManager();
-
-            // Initialize navbar (hover dropdowns, mobile menu, tooltips,
-            // focus trap) — formerly the standalone assets/js/navigation.js IIFE.
-            this.modules.navbar = new Navbar(config);
-            this.modules.navbar.init();
-
-            this._initialized = true;
-            
+        ];
+
+        runSteps(steps).then(() => {
             // Dispatch ready event
             document.dispatchEvent(new CustomEvent('navigation:ready', {
-                detail: { 
+                detail: {
                     modules: Object.keys(this.modules)
                 }
             }));
 
             console.log('Navigation: Successfully initialized modules:', Object.keys(this.modules));
-            
-        } catch (error) {
-            console.error('Navigation: Initialization error', error);
-        }
+        });
 
         return this;
     }

data/assets/js/modules/navigation/scroll-spy.js

@@ -28,6 +28,8 @@
  * - Deterministic, position-based active section (no ratio guessing)
  * - rAF-throttled passive scroll listener; heading offsets are cached and
  *   re-measured on resize / content reflow
+ * - First measurement deferred to idle time so start-up doesn't force a
+ *   synchronous layout of the whole page
  * - Holds the clicked link active while a smooth scroll animates, so
  *   intermediate headings don't flash
  * - Keeps the active link visible inside the TOC without ever scrolling
@@ -83,6 +85,24 @@ function scrollTop() {
     return window.scrollY !== undefined ? window.scrollY : window.pageYOffset;
 }
 
+/** Latest moment (ms) the first measurement may be put off while the page is busy. */
+const IDLE_TIMEOUT_MS = 1500;
+
+/**
+ * Run `fn` when the main thread is idle (requestIdleCallback with a
+ * timeout), or after a short delay where that API is missing (Safari).
+ * @param {Function} fn
+ * @returns {{cancel: Function}}
+ */
+function scheduleIdle(fn) {
+    if (typeof window.requestIdleCallback === 'function') {
+        const id = window.requestIdleCallback(fn, { timeout: IDLE_TIMEOUT_MS });
+        return { cancel: () => window.cancelIdleCallback(id) };
+    }
+    const id = window.setTimeout(fn, 200);
+    return { cancel: () => window.clearTimeout(id) };
+}
+
 export class ScrollSpy {
     constructor() {
         this.tocLinks = getElements(config.selectors.tocLinks);
@@ -100,6 +120,7 @@ export class ScrollSpy {
         this._pendingExpires = 0;
 
         this._resizeObserver = null;
+        this._idleHandle = null;
 
         if (this.headings.length === 0 || this.tocLinks.length === 0) {
             console.log('ScrollSpy: No TOC or headings found, skipping initialization');
@@ -160,6 +181,27 @@ export class ScrollSpy {
         window.addEventListener('wheel', this._onUserScroll, { passive: true });
         window.addEventListener('touchstart', this._onUserScroll, { passive: true });
 
+        // The first measurement reads every heading's position, which forces
+        // a full synchronous layout if it runs while the page is still
+        // loading. On a long quest page that was one of the biggest long
+        // tasks at start-up. The TOC highlight isn't needed for first paint,
+        // so measure once the browser is idle (or after IDLE_TIMEOUT_MS at
+        // the latest), when layout is already done and the reads are cheap.
+        // A scroll before then still updates through the rAF path above.
+        this._idleHandle = scheduleIdle(() => {
+            this._idleHandle = null;
+            this._startMeasuring();
+        });
+
+        console.log(`ScrollSpy: Tracking ${this.headings.length} headings`);
+    }
+
+    /**
+     * Observe content reflow and paint the initial active link.
+     * Runs from idle time (see _init).
+     * @private
+     */
+    _startMeasuring() {
         // Images, embeds, mermaid diagrams and collapsibles change heading
         // offsets after load - re-measure when the content box resizes.
         if (typeof ResizeObserver !== 'undefined') {
@@ -169,8 +211,6 @@ export class ScrollSpy {
         }
 
         this._update();
-
-        console.log(`ScrollSpy: Tracking ${this.headings.length} headings`);
     }
 
     /**
@@ -325,6 +365,11 @@ export class ScrollSpy {
         // heals itself rather than silently disappearing.
         if (this.currentActive === link && link.classList.contains(ACTIVE_CLASS)) return;
 
+        // Read layout for the TOC scroll adjustment BEFORE touching classes:
+        // reading after the class change below would force a synchronous
+        // style + layout pass on every highlight change.
+        const tocScroll = this._measureTocScroll(link);
+
         // Remove previous active state
         this.tocLinks.forEach(l => {
             if (l === link) return;
@@ -338,7 +383,7 @@ export class ScrollSpy {
         this.currentActive = link;
 
         // Scroll TOC to show active link (if needed)
-        this._scrollTocToActiveLink(link);
+        if (tocScroll) tocScroll.container.scrollTop += tocScroll.delta;
 
         // Dispatch custom event for other modules
         document.dispatchEvent(new CustomEvent('navigation:sectionChange', {
@@ -381,18 +426,32 @@ export class ScrollSpy {
      * @param {Element} link
      */
     _scrollTocToActiveLink(link) {
+        const tocScroll = this._measureTocScroll(link);
+        if (tocScroll) tocScroll.container.scrollTop += tocScroll.delta;
+    }
+
+    /**
+     * How far the TOC's scroll container must move to show `link`.
+     * Read-only, so callers can measure before they write.
+     * @private
+     * @param {Element} link
+     * @returns {{container: Element, delta: number}|null}
+     */
+    _measureTocScroll(link) {
         const container = this._getTocScrollContainer(link);
-        if (!container) return;
+        if (!container) return null;
 
         const linkRect = link.getBoundingClientRect();
         const containerRect = container.getBoundingClientRect();
         const margin = 8;
 
         if (linkRect.top < containerRect.top + margin) {
-            container.scrollTop -= (containerRect.top + margin) - linkRect.top;
-        } else if (linkRect.bottom > containerRect.bottom - margin) {
-            container.scrollTop += linkRect.bottom - (containerRect.bottom - margin);
+            return { container, delta: -((containerRect.top + margin) - linkRect.top) };
         }
+        if (linkRect.bottom > containerRect.bottom - margin) {
+            return { container, delta: linkRect.bottom - (containerRect.bottom - margin) };
+        }
+        return null;
     }
 
     /**
@@ -434,6 +493,10 @@ export class ScrollSpy {
             window.removeEventListener('wheel', this._onUserScroll);
             window.removeEventListener('touchstart', this._onUserScroll);
         }
+        if (this._idleHandle) {
+            this._idleHandle.cancel();
+            this._idleHandle = null;
+        }
         if (this._resizeObserver) {
             this._resizeObserver.disconnect();
             this._resizeObserver = null;

data/scripts/ai/api_call.rb

@@ -35,7 +35,7 @@ cfg = begin
 rescue StandardError
   {}
 end
-MODEL   = ENV['AI_MODEL'] || cfg['fallback_model'] || cfg['model'] || 'claude-opus-4-8'
+MODEL   = ENV['AI_MODEL'] || cfg['fallback_model'] || cfg['model'] || 'claude-opus-5-5'
 MAXTOK  = (ENV['AI_MAX_TOKENS'] || cfg['max_tokens'] || 8000).to_i
 VERSION = cfg['api_version'] || '2023-06-01'
 BASE    = cfg['api_base'] || 'https://api.anthropic.com'

data/scripts/ci/test_visual_evidence_autogen.py

@@ -82,6 +82,12 @@ def test_detect_slug() -> None:
     check("reads OUT = 'test/visual/evidence/<slug>' from a hand-rolled one",
           vea.detect_slug("const OUT = 'test/visual/evidence/navbar-fit';") == "navbar-fit")
     check("returns None when nothing names a folder", vea.detect_slug("console.log('hi')") is None)
+    hand_rolled = ("const OUT = path.join(process.cwd(), 'test/visual/evidence/dangling-aria-controls');\n"
+                   "const CASES = [{ slug: 'navbar-toggle-fr-about' }];\n")
+    check("the folder a generator writes to beats a per-case `slug:` key",
+          vea.detect_slug(hand_rolled) == "dangling-aria-controls")
+    check("an explicit `// slug: '…'` comment wins",
+          vea.detect_slug("// slug: 'breadcrumbs'\nconst OUT = 'test/visual/evidence/other';") == "breadcrumbs")
 
 
 def test_plan_pr_454_shape() -> None:
@@ -141,6 +147,51 @@ def test_plan_respects_author_evidence() -> None:
     check("autogen evidence from THIS head is left alone", plan["jobs"] == [])
 
 
+def test_plan_edited_existing_generator() -> None:
+    print("plan — PR edits an existing generator whose folder already has proof")
+    folder = "test/visual/evidence/navbar-tiers-405"
+    files = {GEN_405: GEN_405_SRC, f"{folder}/01-before-after.png": "", f"{folder}/metrics.json": "{}"}
+    plan = plan_for(["_includes/core/header.html", GEN_405], files)
+    check("needed", plan["needed"] is True)
+    check("one bespoke re-render of that generator's folder",
+          len(plan["jobs"]) == 1 and plan["jobs"][0]["kind"] == "bespoke"
+          and plan["jobs"][0]["generator"] == GEN_405 and plan["jobs"][0]["slug"] == "navbar-tiers-405")
+    check("…explained as stale evidence", "predates" in (plan["jobs"][0]["why"] if plan["jobs"] else ""))
+    plan = plan_for([GEN_405], files)
+    check("a generator-only edit (no UI paths) still schedules it", len(plan["jobs"]) == 1)
+    plan = plan_for([GEN_405, f"{folder}/01-before-after.png", f"{folder}/metrics.json"], files)
+    check("…but not when the PR re-rendered that folder itself", plan["jobs"] == [])
+    plan = plan_for(["_layouts/home.html", "test/visual/nameless-evidence.mjs"],
+                    {"test/visual/nameless-evidence.mjs": "console.log('hi')"})
+    check("an edited generator with no detectable slug falls back to the generic job",
+          len(plan["jobs"]) == 1 and plan["jobs"][0]["kind"] == "generic")
+
+
+def test_ensure_jekyll_disables_livereload() -> None:
+    print("render — ensure_jekyll starts the stack with LiveReload off")
+    import contextlib
+    import io
+    import os
+    import tempfile
+    calls = []
+    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: bool(calls)
+            vea.run = lambda cmd, **kw: calls.append((list(cmd), kw.get("env")))
+            with contextlib.redirect_stdout(io.StringIO()):
+                started = vea.ensure_jekyll(5)
+        finally:
+            vea.run, vea.http_ok = real_run, real_http_ok
+            os.chdir(cwd)
+    up = [c for c in calls if c[0][:3] == ["docker", "compose", "up"]]
+    check("we started it", started is True and len(up) == 1)
+    check("with JEKYLL_LIVERELOAD=0 in its environment", bool(up) and (up[0][1] or {}).get("JEKYLL_LIVERELOAD") == "0")
+    wf = (REPO_ROOT / ".github/workflows/visual-evidence-autogen.yml").read_text(encoding="utf-8")
+    check("the workflow also exports JEKYLL_LIVERELOAD: \"0\"", 'JEKYLL_LIVERELOAD: "0"' in wf)
+
+
 def test_plan_out_of_scope() -> None:
     print("plan — nothing visual")
     plan = plan_for(["docs/systems/x.md", "pages/_posts/2026-09-05-x.md", "_data/backlog.yml"], {})
@@ -387,7 +438,8 @@ 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_plan_respects_author_evidence, test_plan_edited_existing_generator,
+              test_ensure_jekyll_disables_livereload, test_plan_out_of_scope, test_styling_matches_ci_filter,
               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,