jekyll-theme-zer0 1.28.0 → 1.30.0

data/assets/js/modules/navigation/config.js

@@ -51,12 +51,15 @@ export const config = {
     // SCROLL SPY SETTINGS
     // ===================================================================
     scrollSpy: {
-        // Root margin for Intersection Observer
-        // Negative values account for fixed headers
-        rootMargin: '-80px 0px -80px 0px',
-        
-        // Intersection threshold levels
-        threshold: [0, 0.25, 0.5, 0.75, 1]
+        // Reading line: distance (px) below the top of the viewport at which a
+        // heading becomes the "current" one. `null` derives it from the
+        // document's `scroll-padding-top` so the highlight matches where
+        // anchor navigation parks a heading; set a number to pin it.
+        offset: null,
+
+        // Slack (px) when comparing a heading against the reading line and
+        // when detecting the bottom of the page.
+        tolerance: 4
     },
 
     // ===================================================================

data/assets/js/modules/navigation/navbar.js

@@ -55,6 +55,7 @@ export class Navbar {
         this._setupMobileDropdowns();
         this._setupOutsideClickClose();
         this._setupOffcanvasReset();
+        this._setupSettingsExclusivity();
         this._setupNavTooltips();
         this._setupDropdownHoverDelay();
         this._setupFocusTrap();
@@ -224,6 +225,60 @@ export class Navbar {
         });
     }
 
+    /**
+     * Mobile: opening Settings from inside a nav panel must not leave the two
+     * stacked on top of each other.
+     *
+     * #bdNavbar (and the optional unified drawer) and #info-section are both
+     * `offcanvas-end` at Bootstrap's $zindex-offcanvas. #bdNavbar additionally
+     * lives inside the fixed header, which _navbar.scss lifts above the
+     * offcanvas backdrop while the menu is open — so a tap on the menu's own
+     * "Settings" item used to open Settings *behind* the still-open menu, with
+     * nothing on screen to show it had worked.
+     *
+     * Intercept the Bootstrap `show` event (capture phase, before Bootstrap's
+     * own handler runs) and defer it until the host panel has finished sliding
+     * out. Doing it on the event rather than on the trigger keeps the plain
+     * data-api working for every other entry point — footer, keyboard, a
+     * consumer's own button — and leaves the markup functional if this module
+     * never loads.
+     */
+    _setupSettingsExclusivity() {
+        const settingsEl = document.getElementById('info-section');
+        if (!settingsEl) return;
+
+        const hostEls = ['bdNavbar', 'zer0UnifiedDrawer']
+            .map((id) => document.getElementById(id))
+            .filter(Boolean);
+        if (!hostEls.length) return;
+
+        this._on(
+            settingsEl,
+            'show.bs.offcanvas',
+            (event) => {
+                const Offcanvas = window.bootstrap?.Offcanvas;
+                if (!Offcanvas) return;
+                const openHost = hostEls.find((el) => el.classList.contains('show'));
+                if (!openHost) return;
+
+                event.preventDefault();
+                event.stopImmediatePropagation();
+
+                const hostInstance = Offcanvas.getInstance(openHost);
+                const show = () => Offcanvas.getOrCreateInstance(settingsEl).show();
+                if (!hostInstance) {
+                    show();
+                    return;
+                }
+                // `hidden.bs.offcanvas` fires after the slide-out transition, so
+                // the header's z-index lift has already been released by then.
+                openHost.addEventListener('hidden.bs.offcanvas', show, { once: true });
+                hostInstance.hide();
+            },
+            true,
+        );
+    }
+
     _setupNavTooltips() {
         if (typeof window.bootstrap === 'undefined' || !window.bootstrap.Tooltip) return;
         const navLinks = document.querySelectorAll('#bdNavbar .nav-link[title]');

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

@@ -1,27 +1,52 @@
 // Feature: ZER0-008
 /**
  * ===================================================================
- * SCROLL SPY - Intersection Observer Implementation
+ * SCROLL SPY - Reading-position TOC highlighting
  * ===================================================================
- * 
+ *
  * File: scroll-spy.js
  * Path: assets/js/modules/navigation/scroll-spy.js
- * Purpose: Track visible sections and highlight corresponding TOC links
- * 
+ * Purpose: Track the section being read and bold its TOC link
+ *
+ * How the active heading is chosen:
+ *   The active heading is the LAST heading whose top has crossed the
+ *   "reading line" - a horizontal line `offset` pixels below the top of the
+ *   viewport, matching the `scroll-padding-top` that anchor navigation uses.
+ *   Once the page is scrolled to the bottom, the last heading wins (trailing
+ *   sections can be shorter than the viewport and would never reach the
+ *   line). The answer is recomputed from scratch on every scroll frame, so
+ *   the highlight cannot drift out of sync with the page.
+ *
+ *   The previous implementation asked IntersectionObserver for the "most
+ *   visible" heading. Headings are only a few pixels tall, so every heading
+ *   inside the observer band reported the same intersectionRatio and the
+ *   winner was whichever entry happened to be in that callback's batch -
+ *   headings leaving the band never triggered a re-evaluation at all. That
+ *   is what made the bolding jump around and stick on the wrong entry.
+ *
  * Features:
- * - Intersection Observer-based (better performance than scroll events)
- * - Active link highlighting with smooth transitions
- * - Auto-scroll TOC to keep active link visible
- * 
+ * - Deterministic, position-based active section (no ratio guessing)
+ * - rAF-throttled passive scroll listener; heading offsets are cached and
+ *   re-measured on resize / content reflow
+ * - 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
+ *   the page itself
+ *
  * Usage:
  *   import { ScrollSpy } from './scroll-spy.js';
  *   const scrollSpy = new ScrollSpy();
- * 
+ *
  * ===================================================================
  */
 
 import { config } from './config.js';
 
+const ACTIVE_CLASS = 'active';
+
+/** How long (ms) to keep a clicked TOC link active while the page animates. */
+const CLICK_GUARD_MS = 1200;
+
 /**
  * Get element safely with error handling
  * @param {string} selector - CSS selector
@@ -50,90 +75,243 @@ function getElements(selector) {
     }
 }
 
+/**
+ * Current vertical scroll position, normalized across browsers.
+ * @returns {number}
+ */
+function scrollTop() {
+    return window.scrollY !== undefined ? window.scrollY : window.pageYOffset;
+}
+
 export class ScrollSpy {
     constructor() {
         this.tocLinks = getElements(config.selectors.tocLinks);
         this.headings = this._getHeadings();
         this.currentActive = null;
-        this.observer = null;
-        
+
+        // Cached measurements - invalidated (not recomputed) by resize and
+        // content reflow, then refreshed inside the next animation frame.
+        this._offsetPx = 0;
+        this._needsMeasure = true;
+        this._frame = null;
+
+        // Click guard: id of the heading a TOC click is scrolling towards.
+        this._pendingId = null;
+        this._pendingExpires = 0;
+
+        this._resizeObserver = null;
+
         if (this.headings.length === 0 || this.tocLinks.length === 0) {
             console.log('ScrollSpy: No TOC or headings found, skipping initialization');
             return;
         }
 
+        this._onScroll = () => this._requestUpdate();
+        this._onReflow = () => this._invalidate();
+        this._onNavigationScroll = event => this._handleNavigationScroll(event);
+        this._onUserScroll = () => this._cancelClickGuard();
+
         this._init();
     }
 
     /**
-     * Get all headings that have corresponding TOC links
+     * Get all headings that have corresponding TOC links, in document order.
+     * Duplicate links to the same heading keep the first link.
      * @private
-     * @returns {Array<{element: Element, link: Element, id: string}>}
+     * @returns {Array<{element: Element, link: Element, id: string, top: number}>}
      */
     _getHeadings() {
         const headings = [];
+        const seen = new Set();
+
         this.tocLinks.forEach(link => {
             const href = link.getAttribute('href');
-            if (href && href.startsWith('#')) {
-                const id = href.substring(1);
-                const heading = document.getElementById(id);
-                if (heading) {
-                    headings.push({
-                        element: heading,
-                        link: link,
-                        id: id
-                    });
-                }
-            }
+            if (!href || !href.startsWith('#') || href.length < 2) return;
+
+            const id = decodeURIComponent(href.substring(1));
+            if (seen.has(id)) return;
+
+            const heading = document.getElementById(id);
+            if (!heading) return;
+
+            seen.add(id);
+            headings.push({ element: heading, link: link, id: id, top: 0 });
         });
+
         return headings;
     }
 
     /**
-     * Initialize Intersection Observer
+     * Attach listeners and paint the initial active link.
      * @private
      */
     _init() {
-        const observerOptions = {
-            root: null,
-            rootMargin: config.scrollSpy.rootMargin,
-            threshold: config.scrollSpy.threshold
-        };
-
-        this.observer = new IntersectionObserver(
-            entries => this._handleIntersection(entries),
-            observerOptions
+        window.addEventListener('scroll', this._onScroll, { passive: true });
+        window.addEventListener('resize', this._onReflow);
+        window.addEventListener('load', this._onReflow);
+        window.addEventListener('hashchange', this._onScroll);
+
+        // A TOC click starts an animated scroll; hold that link active until
+        // the page lands (see _handleNavigationScroll)...
+        document.addEventListener('navigation:scroll', this._onNavigationScroll);
+
+        // ...but a reader who grabs the wheel mid-animation has taken over —
+        // drop the hold and follow them immediately.
+        window.addEventListener('wheel', this._onUserScroll, { passive: true });
+        window.addEventListener('touchstart', this._onUserScroll, { passive: true });
+
+        // Images, embeds, mermaid diagrams and collapsibles change heading
+        // offsets after load - re-measure when the content box resizes.
+        if (typeof ResizeObserver !== 'undefined') {
+            const content = getElement(config.selectors.mainContent) || document.body;
+            this._resizeObserver = new ResizeObserver(this._onReflow);
+            this._resizeObserver.observe(content);
+        }
+
+        this._update();
+
+        console.log(`ScrollSpy: Tracking ${this.headings.length} headings`);
+    }
+
+    /**
+     * Mark cached offsets stale and schedule a recompute.
+     * @private
+     */
+    _invalidate() {
+        this._needsMeasure = true;
+        this._requestUpdate();
+    }
+
+    /**
+     * Coalesce updates into one per animation frame.
+     * @private
+     */
+    _requestUpdate() {
+        if (this._frame !== null) return;
+        this._frame = requestAnimationFrame(() => this._update());
+    }
+
+    /**
+     * Distance (px) from the top of the viewport to the reading line.
+     * Derived from the document's `scroll-padding-top` so the highlight lines
+     * up with where anchor navigation parks a heading; `config.scrollSpy.offset`
+     * pins it explicitly when a fork needs to.
+     * @private
+     * @returns {number}
+     */
+    _readingOffset() {
+        const configured = config.scrollSpy.offset;
+        if (typeof configured === 'number' && Number.isFinite(configured)) {
+            return configured;
+        }
+
+        const padding = parseFloat(
+            getComputedStyle(document.documentElement).scrollPaddingTop
         );
+        if (Number.isFinite(padding)) return padding;
+
+        return config.smoothScroll.offset;
+    }
+
+    /**
+     * Cache each heading's document offset and sort into document order.
+     * @private
+     */
+    _measure() {
+        const offset = scrollTop();
 
-        // Observe all headings
         this.headings.forEach(heading => {
-            this.observer.observe(heading.element);
+            heading.top = heading.element.getBoundingClientRect().top + offset;
         });
+        this.headings.sort((a, b) => a.top - b.top);
 
-        console.log(`ScrollSpy: Observing ${this.headings.length} headings`);
+        this._offsetPx = this._readingOffset();
+        this._needsMeasure = false;
     }
 
     /**
-     * Handle intersection events
+     * True when the page cannot scroll any further down.
      * @private
-     * @param {IntersectionObserverEntry[]} entries
+     * @returns {boolean}
      */
-    _handleIntersection(entries) {
-        // Find the most visible heading
-        let mostVisible = null;
-        let maxRatio = 0;
+    _atBottom() {
+        const doc = document.documentElement;
+        const tolerance = config.scrollSpy.tolerance;
+        return window.innerHeight + scrollTop() >= doc.scrollHeight - tolerance;
+    }
 
-        entries.forEach(entry => {
-            if (entry.isIntersecting && entry.intersectionRatio > maxRatio) {
-                maxRatio = entry.intersectionRatio;
-                mostVisible = this.headings.find(h => h.element === entry.target);
-            }
-        });
+    /**
+     * Resolve which heading the reader is currently in.
+     * @private
+     * @returns {{element: Element, link: Element, id: string, top: number}|null}
+     */
+    _resolveActive() {
+        if (this.headings.length === 0) return null;
+
+        // Trailing sections shorter than the viewport can never reach the
+        // reading line, so the bottom of the page belongs to the last heading.
+        if (this._atBottom()) return this.headings[this.headings.length - 1];
+
+        const line = scrollTop() + this._offsetPx + config.scrollSpy.tolerance;
+
+        let active = null;
+        for (let i = 0; i < this.headings.length; i++) {
+            if (this.headings[i].top > line) break;
+            active = this.headings[i];
+        }
+
+        // Above the first heading, the first section is the one being read.
+        return active || this.headings[0];
+    }
+
+    /**
+     * Recompute and apply the active link. Runs at most once per frame.
+     * @private
+     */
+    _update() {
+        this._frame = null;
+
+        if (this._needsMeasure) this._measure();
+
+        const active = this._resolveActive();
+        if (!active) return;
 
-        // If we found a visible heading, activate it
-        if (mostVisible) {
-            this._setActiveLink(mostVisible.link);
+        if (this._pendingId !== null) {
+            const arrived = active.id === this._pendingId;
+            const expired = performance.now() > this._pendingExpires;
+            if (!arrived && !expired) return;
+            this._pendingId = null;
         }
+
+        this._setActiveLink(active.link);
+    }
+
+    /**
+     * Light the clicked link immediately and hold it until the animated
+     * scroll lands on it, so headings passed on the way don't flash.
+     * @private
+     * @param {CustomEvent} event
+     */
+    _handleNavigationScroll(event) {
+        const targetId = event && event.detail ? event.detail.targetId : null;
+        if (!targetId) return;
+
+        const heading = this.headings.find(h => h.id === targetId);
+        if (!heading) return;
+
+        this._pendingId = targetId;
+        this._pendingExpires = performance.now() + CLICK_GUARD_MS;
+        this._setActiveLink(heading.link);
+    }
+
+    /**
+     * Release the click guard so the positional rule takes over again.
+     * @private
+     */
+    _cancelClickGuard() {
+        if (this._pendingId === null) return;
+        this._pendingId = null;
+        this._requestUpdate();
     }
 
     /**
@@ -142,44 +320,78 @@ export class ScrollSpy {
      * @param {Element} link
      */
     _setActiveLink(link) {
-        if (this.currentActive === link) return;
+        if (!link) return;
+        // Re-apply if something else stripped the class, so the highlight
+        // heals itself rather than silently disappearing.
+        if (this.currentActive === link && link.classList.contains(ACTIVE_CLASS)) return;
 
         // Remove previous active state
-        this.tocLinks.forEach(l => l.classList.remove('active'));
+        this.tocLinks.forEach(l => {
+            if (l === link) return;
+            l.classList.remove(ACTIVE_CLASS);
+            l.removeAttribute('aria-current');
+        });
 
         // Add active state
-        if (link) {
-            link.classList.add('active');
-            this.currentActive = link;
-
-            // Scroll TOC to show active link (if needed)
-            this._scrollTocToActiveLink(link);
-
-            // Dispatch custom event for other modules
-            document.dispatchEvent(new CustomEvent('navigation:sectionChange', {
-                detail: { 
-                    link: link,
-                    href: link.getAttribute('href')
-                }
-            }));
+        link.classList.add(ACTIVE_CLASS);
+        link.setAttribute('aria-current', 'true');
+        this.currentActive = link;
+
+        // Scroll TOC to show active link (if needed)
+        this._scrollTocToActiveLink(link);
+
+        // Dispatch custom event for other modules
+        document.dispatchEvent(new CustomEvent('navigation:sectionChange', {
+            detail: {
+                link: link,
+                href: link.getAttribute('href')
+            }
+        }));
+    }
+
+    /**
+     * Nearest scrollable ancestor of the TOC link, if any.
+     * `.bd-toc` scrolls on desktop and `.offcanvas-body` on mobile, so the
+     * container is resolved at call time rather than assumed.
+     * @private
+     * @param {Element} link
+     * @returns {Element|null}
+     */
+    _getTocScrollContainer(link) {
+        const hinted = getElement(config.selectors.tocContainer);
+        const scrolls = el =>
+            el.scrollHeight > el.clientHeight + 1 &&
+            /(auto|scroll)/.test(getComputedStyle(el).overflowY);
+
+        if (hinted && hinted.contains(link) && scrolls(hinted)) return hinted;
+
+        let node = link.parentElement;
+        while (node && node !== document.body) {
+            if (scrolls(node)) return node;
+            node = node.parentElement;
         }
+        return null;
     }
 
     /**
-     * Scroll TOC container to show active link
+     * Keep the active link visible inside the TOC's own scroll container.
+     * Adjusts `scrollTop` directly - `scrollIntoView()` would bubble up and
+     * scroll the page, which feeds straight back into the spy.
      * @private
      * @param {Element} link
      */
     _scrollTocToActiveLink(link) {
-        const tocContainer = getElement(config.selectors.tocContainer);
-        if (!tocContainer) return;
+        const container = this._getTocScrollContainer(link);
+        if (!container) return;
 
         const linkRect = link.getBoundingClientRect();
-        const containerRect = tocContainer.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        const margin = 8;
 
-        // Check if link is out of view
-        if (linkRect.top < containerRect.top || linkRect.bottom > containerRect.bottom) {
-            link.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        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);
         }
     }
 
@@ -204,14 +416,37 @@ export class ScrollSpy {
     }
 
     /**
-     * Cleanup observer
+     * Cleanup listeners and observers
      */
     destroy() {
-        if (this.observer) {
-            this.observer.disconnect();
-            this.observer = null;
+        if (this._onScroll) {
+            window.removeEventListener('scroll', this._onScroll);
+            window.removeEventListener('hashchange', this._onScroll);
+        }
+        if (this._onReflow) {
+            window.removeEventListener('resize', this._onReflow);
+            window.removeEventListener('load', this._onReflow);
         }
-        this.tocLinks.forEach(l => l.classList.remove('active'));
+        if (this._onNavigationScroll) {
+            document.removeEventListener('navigation:scroll', this._onNavigationScroll);
+        }
+        if (this._onUserScroll) {
+            window.removeEventListener('wheel', this._onUserScroll);
+            window.removeEventListener('touchstart', this._onUserScroll);
+        }
+        if (this._resizeObserver) {
+            this._resizeObserver.disconnect();
+            this._resizeObserver = null;
+        }
+        if (this._frame !== null) {
+            cancelAnimationFrame(this._frame);
+            this._frame = null;
+        }
+
+        this.tocLinks.forEach(l => {
+            l.classList.remove(ACTIVE_CLASS);
+            l.removeAttribute('aria-current');
+        });
         this.currentActive = null;
         console.log('ScrollSpy: Destroyed');
     }

data/assets/js/modules/theme/appearance.js

@@ -123,9 +123,15 @@
             // the panel's other h6 section headings.
             wrapper.className = 'zer0-appearance-panel mb-4';
             wrapper.innerHTML =
-                '<h6 id="zer0-appearance-heading" class="text-body-secondary small text-uppercase fw-semibold mb-2">' +
+                // h3, not h6: this panel mounts inside the Settings offcanvas,
+                // whose title is an <h2>, alongside the Liquid-rendered section
+                // labels that are also <h3 class="h6">. The tag carries DEPTH,
+                // the .h6 class carries SIZE (#436). Injected at runtime, so no
+                // source grep finds it -- only a rendered test does, which is
+                // how this one was caught.
+                '<h3 id="zer0-appearance-heading" class="h6 text-body-secondary small text-uppercase fw-semibold mb-2">' +
                   '<i class="bi bi-eyedropper me-1" aria-hidden="true"></i>Primary Color' +
-                '</h6>' +
+                '</h3>' +
                 pickerHtml('visually-hidden') +
                 '<button type="button" class="btn btn-link btn-sm p-0" data-appearance-reset>' +
                   '<i class="bi bi-arrow-counterclockwise me-1" aria-hidden="true"></i>Reset color' +

data/assets/js/obsidian-wiki-links.js

@@ -213,9 +213,14 @@
     if (node.nodeType !== Node.TEXT_NODE) return false;
     var parent = node.parentNode;
     while (parent && parent !== document.body) {
-      var tag = parent.nodeName;
-      if (tag === 'CODE' || tag === 'PRE' || tag === 'A' || tag === 'SCRIPT' || tag === 'STYLE') return false;
-      if (parent.classList && (parent.classList.contains('mermaid') || parent.classList.contains('obsidian-embed'))) return false;
+      // Upper-case the name: HTML elements report "STYLE" but elements in
+      // the SVG namespace report "style", so an SVG <style> slipped through
+      // and had its `#id` selectors rewritten into tag links. Inline SVG
+      // (Mermaid diagrams, icons) is graphics, never prose — skip the whole
+      // subtree rather than special-casing its children.
+      var tag = String(parent.nodeName || '').toUpperCase();
+      if (tag === 'CODE' || tag === 'PRE' || tag === 'A' || tag === 'SCRIPT' || tag === 'STYLE' || tag === 'SVG') return false;
+      if (parent.classList && (parent.classList.contains('mermaid') || parent.classList.contains('zer0-diagram') || parent.classList.contains('obsidian-embed'))) return false;
       parent = parent.parentNode;
     }
     var text = node.nodeValue;