jekyll-theme-zer0 1.24.0 → 1.25.0

data/assets/js/halfmoon.js

@@ -30,36 +30,37 @@
   setTheme(getPreferredTheme())
 
   const showActiveTheme = (theme, focus = false) => {
-    const themeSwitcher = document.querySelector('#bd-theme')
-
-    if (!themeSwitcher) {
-      return
-    }
-
-    const themeSwitcherText = document.querySelector('#bd-theme-text')
-    const activeThemeIcon = document.querySelector('.theme-icon-active use')
-    const btnToActive = document.querySelector(`[data-bs-theme-value="${theme}"]`)
-    const themeIconUse = btnToActive?.querySelector('svg use')
-    if (!btnToActive || !themeIconUse || !activeThemeIcon) {
+    const activeButtons = document.querySelectorAll(`[data-bs-theme-value="${theme}"]`)
+    if (!activeButtons.length) {
       return
     }
 
-    const svgOfActiveBtn = themeIconUse.getAttribute('href')
-
+    // The control can render more than once per page (settings offcanvas +
+    // theme-controls-bar), so sync active state across every instance.
     document.querySelectorAll('[data-bs-theme-value]').forEach(element => {
       element.classList.remove('active')
       element.setAttribute('aria-pressed', 'false')
     })
+    activeButtons.forEach(element => {
+      element.classList.add('active')
+      element.setAttribute('aria-pressed', 'true')
+    })
 
-    btnToActive.classList.add('active')
-    btnToActive.setAttribute('aria-pressed', 'true')
-    activeThemeIcon.setAttribute('href', svgOfActiveBtn)
-    const baseLabel = themeSwitcherText?.textContent?.trim() || 'Toggle theme'
-    const themeSwitcherLabel = `${baseLabel} (${btnToActive.dataset.bsThemeValue})`
-    themeSwitcher.setAttribute('aria-label', themeSwitcherLabel)
-
-    if (focus) {
-      themeSwitcher.focus()
+    // Legacy dropdown affordances (#bd-theme toggle with a mirrored icon) —
+    // updated only when that markup is present.
+    const themeSwitcher = document.querySelector('#bd-theme')
+    const activeThemeIcon = document.querySelector('.theme-icon-active use')
+    const themeIconUse = activeButtons[0].querySelector('svg use')
+    if (activeThemeIcon && themeIconUse) {
+      activeThemeIcon.setAttribute('href', themeIconUse.getAttribute('href'))
+    }
+    if (themeSwitcher) {
+      const themeSwitcherText = document.querySelector('#bd-theme-text')
+      const baseLabel = themeSwitcherText?.textContent?.trim() || 'Toggle theme'
+      themeSwitcher.setAttribute('aria-label', `${baseLabel} (${theme})`)
+      if (focus) {
+        themeSwitcher.focus()
+      }
     }
   }
 

data/assets/js/modules/navigation/gestures.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-009
 /**
  * ===================================================================
  * SWIPE GESTURES - Mobile Offcanvas Control

data/assets/js/modules/navigation/keyboard.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-009
 /**
  * ===================================================================
  * KEYBOARD SHORTCUTS - Navigation Enhancements

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

@@ -1,3 +1,4 @@
+// Feature: ZER0-008
 /**
  * ===================================================================
  * SCROLL SPY - Intersection Observer Implementation

data/assets/js/modules/navigation/sidebar-state.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-008
 /**
  * ===================================================================
  * SIDEBAR STATE - Persistence and State Management

data/assets/js/modules/navigation/sidebar-visibility.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-008
 /**
  * ===================================================================
  * SIDEBAR VISIBILITY - Hide/show left docs sidebar with persistence

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

@@ -1,3 +1,4 @@
+// Feature: ZER0-008
 /**
  * ===================================================================
  * SMOOTH SCROLL - Enhanced Anchor Navigation

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

@@ -1,3 +1,4 @@
+// Feature: ZER0-031
 /**
  * ===================================================================
  * APPEARANCE — Runtime theme controls (color mode + primary color)
@@ -11,13 +12,20 @@
  *
  *   - Color mode buttons (light / dark / auto) — writes data-bs-theme
  *     to <html> and persists to localStorage["theme"] (compatible with
- *     halfmoon.js so both stay in sync).
+ *     halfmoon.js so both stay in sync). Skipped in the settings
+ *     offcanvas (compact mode), where the halfmoon segmented control
+ *     directly above already owns color mode.
  *
  *   - Primary color picker — writes to localStorage["zer0-appearance"]
  *     and updates --zer0-color-primary live so every component that uses
  *     the token (buttons, callouts, FABs, focus rings) reflects the
  *     change without a reload. Cleared by the Reset button.
  *
+ * Host resolution: an explicit [data-appearance-panel-host] (e.g. the
+ * theme-preview sidebar) gets the full panel; otherwise the panel
+ * mounts compactly into #zer0AppearanceSlot inside the Settings
+ * offcanvas Appearance tab (legacy fallback: the offcanvas body).
+ *
  * Initial paint is already handled by the script emitted in
  * _includes/core/tokens-inline.html so there is no flash of default
  * color when the page loads.
@@ -33,6 +41,7 @@
     const STORAGE_KEY = 'zer0-appearance';
     const THEME_KEY = 'theme';
     const PANEL_HOST_SELECTOR = '[data-appearance-panel-host]';
+    const SLOT_HOST_SELECTOR = '#zer0AppearanceSlot';
     const FALLBACK_HOST_SELECTOR = '#info-section .offcanvas-body';
 
     function readPrefs() {
@@ -75,18 +84,15 @@
         try { localStorage.setItem(THEME_KEY, mode); } catch (e) { /* ignore */ }
     }
 
-    function buildPanel(host) {
+    function buildPanel(host, compact) {
         const prefs = readPrefs();
         const mode = resolveColorMode();
         const primary = prefs.primary || getInitialPrimary();
 
         const wrapper = document.createElement('section');
-        wrapper.className = 'zer0-appearance-panel border rounded p-3 mt-3';
         wrapper.setAttribute('aria-labelledby', 'zer0-appearance-heading');
-        wrapper.innerHTML =
-            '<h3 id="zer0-appearance-heading" class="h6 mb-3">' +
-              '<i class="bi bi-palette me-2" aria-hidden="true"></i>Appearance' +
-            '</h3>' +
+
+        const modeGroupHtml =
             '<div class="mb-3" role="group" aria-label="Color mode">' +
               '<label class="form-label small text-body-secondary mb-2">Color mode</label>' +
               '<div class="btn-group w-100" role="group">' +
@@ -97,18 +103,45 @@
                 '<button type="button" class="btn btn-outline-secondary btn-sm" data-mode="auto">' +
                   '<i class="bi bi-circle-half me-1" aria-hidden="true"></i>Auto</button>' +
               '</div>' +
-            '</div>' +
+            '</div>';
+
+        // In compact mode the section heading is the visible label, so the
+        // <label> stays for assistive tech but is visually hidden.
+        const pickerHtml = (labelClass) =>
             '<div class="mb-3">' +
-              '<label for="zer0-appearance-primary" class="form-label small text-body-secondary">' +
+              '<label for="zer0-appearance-primary" class="' + labelClass + '">' +
                 'Primary color</label>' +
               '<input type="color" id="zer0-appearance-primary" class="form-control form-control-color" ' +
                 'aria-describedby="zer0-appearance-primary-help">' +
               '<div id="zer0-appearance-primary-help" class="form-text small">' +
                 'Overrides <code>--zer0-color-primary</code> across the theme.</div>' +
-            '</div>' +
-            '<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 to defaults' +
-            '</button>';
+            '</div>';
+
+        if (compact) {
+            // Settings offcanvas: color mode lives in the halfmoon control just
+            // above, so render only the primary-color section, styled to match
+            // 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">' +
+                  '<i class="bi bi-eyedropper me-1" aria-hidden="true"></i>Primary Color' +
+                '</h6>' +
+                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' +
+                '</button>';
+        } else {
+            wrapper.className = 'zer0-appearance-panel border rounded p-3 mt-3';
+            wrapper.innerHTML =
+                '<h3 id="zer0-appearance-heading" class="h6 mb-3">' +
+                  '<i class="bi bi-palette me-2" aria-hidden="true"></i>Appearance' +
+                '</h3>' +
+                modeGroupHtml +
+                pickerHtml('form-label small text-body-secondary') +
+                '<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 to defaults' +
+                '</button>';
+        }
 
         host.appendChild(wrapper);
 
@@ -116,7 +149,7 @@
         const picker = wrapper.querySelector('#zer0-appearance-primary');
         picker.value = hexishOrDefault(primary, '#007bff');
 
-        // Wire color-mode buttons
+        // Wire color-mode buttons (full panel only)
         wrapper.querySelectorAll('[data-mode]').forEach((btn) => {
             const m = btn.dataset.mode;
             btn.setAttribute('aria-pressed', String(m === mode));
@@ -183,10 +216,13 @@
     }
 
     function mount() {
-        const host = document.querySelector(PANEL_HOST_SELECTOR) || document.querySelector(FALLBACK_HOST_SELECTOR);
+        const explicitHost = document.querySelector(PANEL_HOST_SELECTOR);
+        const host = explicitHost
+            || document.querySelector(SLOT_HOST_SELECTOR)
+            || document.querySelector(FALLBACK_HOST_SELECTOR);
         if (!host) return; // info-section not present on this page
         if (host.querySelector('.zer0-appearance-panel')) return; // already mounted
-        buildPanel(host);
+        buildPanel(host, !explicitHost);
     }
 
     if (document.readyState === 'loading') {

data/assets/js/nanobar-init.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-066
 /**
  * Nanobar Initialization — config-driven page-load progress bar.
  *

data/assets/js/navigation.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-055
 /**
  * ==============================================================================
  * NAVIGATION SCRIPTS — DEPRECATED

data/assets/js/obsidian-graph.js

@@ -1,3 +1,4 @@
+// Features: ZER0-044, ZER0-045
 /*
  * obsidian-graph.js
  *

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

@@ -1,3 +1,4 @@
+// Feature: ZER0-044
 /*
  * obsidian-wiki-links.js
  *

data/assets/js/palette-generator.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-065
 /**
  * palette-generator.js
  * Color palette generator + live CSS variable editor for the Theme Customizer.

data/assets/js/particles-source.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-034
 /* -----------------------------------------------
 /* Author : 
 /* MIT license: http://opensource.org/licenses/MIT

data/assets/js/search-modal.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-032
 /**
  * Search Modal Controller
  * - Opens modal on navigation:searchRequest event ("/" shortcut)

data/assets/js/setup-wizard.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-067
 /**
  * ===================================================================
  * Setup Wizard — _config.yml Generator

data/assets/js/share-actions.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-069
 (function () {
   'use strict';
 

data/assets/js/skin-editor.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-065
 /**
  * skin-editor.js — Colorffy-inspired skin editor for zer0-mistakes theme
  *

data/assets/js/table-copy.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-068
 /**
  * Content table CSV copy — injects a toolbar button on markdown/HTML tables
  * in main reading areas. Scoped to content wrappers; skips admin and sitemap.

data/assets/js/theme-customizer.js

@@ -1,3 +1,4 @@
+// Feature: ZER0-065
 /**
  * theme-customizer.js
  * Powers the Theme Customizer admin page.

data/scripts/analyze-commits.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-015, ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/utils/analyze-commits

data/scripts/bin/giscus-discussions

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-035, ZER0-073
 
 # giscus-discussions — read, draft, and post the GitHub Discussions that back
 # the site's Giscus comment threads. This is the engine the Claude Code

data/scripts/bin/install

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Feature: ZER0-003
 # scripts/bin/install — zer0-mistakes installer entrypoint (v2)
 #
 # Routes to scripts/install/cli.sh (new spec-driven architecture).

data/scripts/bin/validate

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Feature: ZER0-048
 
 # Canonical preflight validator for zer0-mistakes.
 # Usage: ./scripts/bin/validate [options]

data/scripts/build

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Feature: ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/bin/build

data/scripts/content-review.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# Feature: ZER0-072
 # frozen_string_literal: true
 
 # =============================================================================

data/scripts/convert-notebooks.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-012, ZER0-028
 #
 # Script Name: convert-notebooks.sh
 # Description: Converts Jupyter notebooks (.ipynb) to Jekyll-compatible Markdown
@@ -339,7 +340,7 @@ clean_converted() {
                 rm -f "$md_file"
                 info "Removed: $md_file"
             fi
-            ((count++))
+            count=$((count + 1))
         fi
     done < <(find "$OUTPUT_DIR" -name "*.md" -print0 2>/dev/null)
     
@@ -364,7 +365,7 @@ list_notebooks() {
     else
         while IFS= read -r -d '' notebook_file; do
             echo "$notebook_file"
-            ((count++))
+            count=$((count + 1))
         done < <(find "$NOTEBOOKS_DIR" -name "*.ipynb" -print0 2>/dev/null)
     fi
     
@@ -400,7 +401,7 @@ main() {
         local count=0
         while IFS= read -r -d '' notebook_file; do
             convert_notebook "$notebook_file"
-            ((count++))
+            count=$((count + 1))
         done < <(find "$NOTEBOOKS_DIR" -name "*.ipynb" -print0 2>/dev/null)
         
         if [[ $count -eq 0 ]]; then

data/scripts/fix-markdown-format.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Feature: ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/utils/fix-markdown

data/scripts/generate-preview-images.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-004, ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/features/generate-preview-images

data/scripts/generate-roadmap.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Feature: ZER0-052
 # =============================================================================
 # generate-roadmap.sh
 # =============================================================================

data/scripts/install-preview-generator.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Feature: ZER0-004
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/features/install-preview-generator

data/scripts/release

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-015, ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/bin/release

data/scripts/requirements.txt

@@ -0,0 +1,11 @@
+# Python toolchain for repository automation scripts.
+#
+# Currently the notebook-conversion pipeline: scripts/convert-notebooks.sh and
+# .github/workflows/convert-notebooks.yml use nbconvert to render
+# pages/_notebooks/*.ipynb into Jekyll-compatible Markdown.
+#
+# This file also acts as the pip cache key for actions/setup-python in that
+# workflow (see `cache-dependency-path`). Keep it in sync with the toolchain the
+# scripts import; a missing file here makes `cache: pip` hard-fail the run.
+jupyter
+nbconvert

data/scripts/setup.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Features: ZER0-002, ZER0-028
 
 # ============================================================================
 # WRAPPER: This script forwards to scripts/utils/setup

data/scripts/tag-features

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# tag-features — reverse-traceability enforcement for the feature registry.
+#
+# Every source file a feature lists under `references:` carries a top-of-file
+# `Feature: ZER0-NNN` comment, so the link runs both ways (registry -> code and
+# code -> registry). This tool is the single source of truth for that rule:
+#
+#   ruby scripts/tag-features            # --check (default): exit 1 + list any
+#                                        #   referenced source file missing its tag
+#   ruby scripts/tag-features --write    # insert the missing tags (idempotent,
+#                                        #   line-ending-preserving)
+#
+# The `features` test suite runs `--check`, so a new feature that forgets to tag
+# its files fails CI. Governance: .github/instructions/features.instructions.md.
+#
+# Scope (mirrors what a feature's references implement, and only what can carry a
+# comment): .rb .js .mjs .scss .sh .html .yml, plus Dockerfile/Makefile and the
+# scripts/{bin/*,build,release} wrappers. Excluded by design: markdown docs,
+# JSON (no comment syntax), vendored/minified third-party libs, directory refs,
+# and _config.yml (it has an exact-copy admin mirror enforced elsewhere).
+#
+# Portable across Ruby 2.6 (macOS system) and 3.x (CI/Docker).
+# ---------------------------------------------------------------------------
+
+require 'date'
+require 'yaml'
+
+MIRROR = '_data/features.yml'
+MODE = ARGV.include?('--write') ? :write : :check
+
+CODE_EXT = %w[.rb .js .mjs .scss .sh .html .yml].freeze
+SLASH_EXT = %w[.js .mjs .scss].freeze
+NOEXT_FILES = %w[docker/Dockerfile Makefile scripts/release scripts/build].freeze
+EXCLUDE_FILES = %w[_config.yml assets/js/particles.js assets/js/halfmoon.js].freeze
+
+def load_yaml(path)
+  YAML.load_file(path, permitted_classes: [Date, Time], aliases: true)
+rescue ArgumentError
+  YAML.load_file(path)
+end
+
+def ref_paths(refs)
+  return [] unless refs.is_a?(Hash)
+
+  refs.values.flat_map { |v| v.is_a?(Array) ? v : [v] }.select { |v| v.is_a?(String) }
+end
+
+def vendored?(path)
+  path.include?('/vendor/') || path.end_with?('.min.js') || EXCLUDE_FILES.include?(path)
+end
+
+# Which referenced paths must carry a tag.
+def taggable?(path)
+  return false if path.end_with?('/') || vendored?(path)
+
+  ext = File.extname(path)
+  return false if %w[.md .json].include?(ext)
+
+  CODE_EXT.include?(ext) || NOEXT_FILES.include?(path) || (path.start_with?('scripts/bin/') && ext.empty?)
+end
+
+def tag_text(ids)
+  (ids.length == 1 ? 'Feature: ' : 'Features: ') + ids.join(', ')
+end
+
+def already_tagged?(raw, ids)
+  head = raw[0, 500].to_s
+  ids.any? { |id| head.include?(id) }
+end
+
+# Insert the tag with type-aware placement, preserving the file's line endings.
+def insert_tag(path, ids)
+  raw = File.binread(path).force_encoding('UTF-8')
+  return :skipped if already_tagged?(raw, ids)
+
+  nl = raw.include?("\r\n") ? "\r\n" : "\n"
+  ext = File.extname(path)
+  tag = tag_text(ids)
+  lines = raw.each_line.to_a
+
+  if ext == '.html' && raw.lstrip.start_with?('---')
+    idx = lines.index { |l| l.strip == '---' } || 0
+    lines.insert(idx + 1, "# #{tag}#{nl}")            # invisible YAML front-matter comment
+  elsif ext == '.html'
+    lines.unshift("{% comment %} #{tag} {% endcomment %}#{nl}")  # stripped at build
+  else
+    prefix = SLASH_EXT.include?(ext) ? '//' : '#'
+    line = "#{prefix} #{tag}#{nl}"
+    first = lines[0].to_s
+    if first.start_with?('#!') || first.lstrip.start_with?('# syntax=') || first.lstrip.start_with?('# escape=')
+      lines.insert(1, line)                            # keep shebang / Dockerfile directive on line 1
+    else
+      lines.unshift(line)
+    end
+  end
+
+  File.binwrite(path, lines.join)
+  :written
+end
+
+data = load_yaml(MIRROR)
+feats = data && data['features']
+abort 'tag-features: could not read features registry' unless feats.is_a?(Array)
+
+by_file = Hash.new { |h, k| h[k] = [] }
+feats.each do |f|
+  next if f['implemented'] == false   # removed features keep (absent) refs; nothing to tag
+
+  ref_paths(f['references']).each do |p|
+    by_file[p] << f['id'] if taggable?(p) && File.exist?(p)
+  end
+end
+
+if MODE == :write
+  written = 0
+  by_file.each { |path, ids| written += 1 if insert_tag(path, ids.uniq.sort) == :written }
+  puts "tag-features: wrote #{written} tag(s); #{by_file.size - written} already current"
+  exit 0
+end
+
+missing = by_file.reject do |path, ids|
+  already_tagged?(File.binread(path).force_encoding('UTF-8'), ids.uniq.sort)
+end
+
+if missing.empty?
+  puts "tag-features: all #{by_file.size} referenced source files carry their Feature tag"
+  exit 0
+end
+
+warn "tag-features: #{missing.length} referenced source file(s) missing a `Feature: ZER0-NNN` comment:"
+missing.each { |path, ids| warn "  - #{path}  (needs #{ids.uniq.sort.join(', ')})" }
+warn 'Fix: run `ruby scripts/tag-features --write` (or add the comment by hand).'
+exit 1

data/scripts/validate-features.rb

@@ -81,6 +81,13 @@ feats.each_with_index do |f, i|
     die "#{id}: required field `#{key}` is missing/empty" if val.nil? || (val.respond_to?(:empty?) && val.empty?)
   end
 
+  # Title/description are rendered UNwrapped into HTML on /features/; a raw
+  # angle bracket (e.g. "/authors/<key>/") becomes a stray tag that swallows
+  # every following card. Keep them plain prose.
+  %w[title description].each do |key|
+    die "#{id}: `#{key}` must not contain raw `<`/`>` (breaks HTML on /features/ — use :key or &lt;)" if f[key].to_s =~ /[<>]/
+  end
+
   die "#{id}: id must match ZER0-NNN" unless f['id'] =~ /\AZER0-\d{3}\z/
   die "#{id}: duplicate id" if seen[f['id']]
   seen[f['id']] = true

data/scripts/vendor-install.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Feature: ZER0-053
 
 # Vendor asset installer for zer0-mistakes Jekyll theme
 # Downloads third-party JS/CSS libraries defined in vendor-manifest.json