jekyll-theme-zer0 0.22.19 → 0.22.21

data/_includes/components/nanobar.html

@@ -0,0 +1,117 @@
+<!--
+  ===================================================================
+  NANOBAR - Config-Driven Page Loading Progress Bar
+  ===================================================================
+
+  File: nanobar.html
+  Path: _includes/components/nanobar.html
+  Purpose: Visual loading indicator shown on every page load,
+           fully configurable via site.nanobar in _config.yml
+
+  Template Logic:
+  - Conditionally renders only when site.nanobar.enabled != false
+  - Injects CSS custom properties from _config.yml values
+  - Loads nanobar.min.js (library) and nanobar-init.js (initializer)
+  - Passes config to JS via window.zer0Nanobar object
+
+  Dependencies:
+  - assets/js/nanobar.min.js  — third-party Nanobar library
+  - assets/js/nanobar-init.js — theme initializer script
+  - _includes/core/header.html — #top-progress-target mount point
+    (rendered only when position == "navbar")
+
+  Configuration (_config.yml → nanobar):
+    enabled       : true | false          # master switch
+    color         : CSS color value       # bar fill colour
+    background    : CSS color value       # track background
+    height        : CSS length            # bar thickness
+    position      : top | bottom | navbar # placement mode
+    z_index       : integer               # stacking order
+    steps         : [int, …]              # progress percentages
+    step_delay_ms : integer               # ms between steps
+    classname     : string                # CSS class on wrapper
+    id            : string                # DOM id
+    target        : CSS selector | ""     # explicit mount target
+
+  Performance Notes:
+  - Both scripts loaded with `defer` to avoid blocking rendering
+  - CSS custom properties keep the inline <style> minimal
+  - Library injects its own baseline CSS; theme overrides via
+    specificity and !important where needed
+
+  Library: https://github.com/jacoborus/nanobar
+  ===================================================================
+-->
+
+{%- assign nb = site.nanobar | default: empty -%}
+{%- if nb == empty or nb.enabled != false -%}
+
+{%- comment -%} ── Resolve config with safe defaults ── {%- endcomment -%}
+{%- assign nb_color      = nb.color         | default: "var(--bs-primary)" -%}
+{%- assign nb_bg         = nb.background    | default: "transparent" -%}
+{%- assign nb_height     = nb.height        | default: "3px" -%}
+{%- assign nb_position   = nb.position      | default: "top" -%}
+{%- assign nb_zindex     = nb.z_index       | default: 9999 -%}
+{%- assign nb_classname  = nb.classname     | default: "nanobar" -%}
+{%- assign nb_id         = nb.id            | default: "top-progress-bar" -%}
+{%- assign nb_target     = nb.target        | default: "" -%}
+{%- assign nb_step_delay = nb.step_delay_ms | default: 0 -%}
+{%- assign nb_steps      = nb.steps -%}
+{%- if nb_steps == nil or nb_steps == empty -%}
+  {%- assign nb_steps = "30,76,100" | split: "," -%}
+{%- endif -%}
+
+<!-- ── Nanobar theme CSS (config-driven custom properties) ── -->
+<style id="nanobar-theme">
+  :root {
+    --nanobar-color:  {{ nb_color }};
+    --nanobar-bg:     {{ nb_bg }};
+    --nanobar-height: {{ nb_height }};
+    --nanobar-z:      {{ nb_zindex }};
+  }
+
+  /* Override library defaults with theme values */
+  .{{ nb_classname }} {
+    height: var(--nanobar-height) !important;
+    background: var(--nanobar-bg);
+    z-index: var(--nanobar-z);
+  }
+  .{{ nb_classname }} .bar {
+    background: var(--nanobar-color) !important;
+    transition: width .2s ease, height .3s ease;
+  }
+
+  /* Position modifiers */
+  .{{ nb_classname }}--bottom { top: auto !important; bottom: 0; }
+
+  /* Navbar mount: inline strip under the header */
+  .nanobar-mount {
+    position: relative;
+    width: 100%;
+    height: var(--nanobar-height);
+    overflow: hidden;
+  }
+  .nanobar-mount > .{{ nb_classname }}--navbar {
+    position: absolute !important;
+    top: 0; left: 0; right: 0;
+    width: 100%;
+  }
+</style>
+
+<!-- ── Nanobar scripts ── -->
+<script defer src="{{ '/assets/js/nanobar.min.js' | relative_url }}"></script>
+<script defer src="{{ '/assets/js/nanobar-init.js' | relative_url }}"></script>
+
+<!-- ── Bridge _config.yml values to JS ── -->
+<script>
+  window.zer0Nanobar = {
+    classname: {{ nb_classname | jsonify }},
+    id:        {{ nb_id        | jsonify }},
+    position:  {{ nb_position  | jsonify }},
+    target:    {{ nb_target    | jsonify }},
+    steps:     [{% for s in nb_steps %}{{ s | strip | plus: 0 }}{% unless forloop.last %},{% endunless %}{% endfor %}],
+    stepDelay: {{ nb_step_delay | plus: 0 }}
+  };
+</script>
+
+{%- endif -%}

data/_includes/core/footer.html

@@ -30,10 +30,10 @@
   ===================================================================
 -->
 
-<footer class="bd-footer container-xl border-top" role="contentinfo">
+<footer class="bd-footer border-top" role="contentinfo">
   <!-- Powered by Row -->
-  <div class="container row my-3">
-    <ul class="nav col-sm justify-content-end list-unstyled d-flex align-items-center" aria-label="Powered by technologies">
+  <div class="container-xl my-3">
+    <ul class="nav justify-content-end list-unstyled d-flex align-items-center flex-wrap" aria-label="Powered by technologies">
       <span class="align-start">
         &copy; {{ site.time | date: "%Y" }} {{ site.name | default: site.title }} — Powered by:
       </span>
@@ -67,10 +67,9 @@
     </ul>
   </div>
 
-  <!-- Branding and Navigation Block -->
-  <div class="container row">
-    <div class="container bg-dark text-light py-5 rounded-3">
-      <div class="container">
+  <!-- Branding and Navigation Block — full-width dark background -->
+  <div class="bg-dark text-light py-5">
+    <div class="container-xl">
         <!-- Top: Site info + Quick Links + Social -->
         <div class="row mb-4">
           <!-- Site Info -->
@@ -163,10 +162,9 @@
           </div>
         </div>
 
-        <!-- Bottom: Copyright -->
-        <div class="text-center">
-          <p class="mb-0">&copy; {{ site.time | date: "%Y" }} {{ site.title | default: site.name }}. All Rights Reserved.</p>
-        </div>
+      <!-- Bottom: Copyright -->
+      <div class="text-center">
+        <p class="mb-0">&copy; {{ site.time | date: "%Y" }} {{ site.title | default: site.name }}. All Rights Reserved.</p>
       </div>
     </div>
   </div>

data/_includes/core/head.html

@@ -12,7 +12,7 @@
   - Loads critical JavaScript libraries before page render
   - Includes SEO optimization and social media meta tags
   - Configures third-party integrations (Analytics, MathJax)
-  - Sets up progress bar and UI enhancement scripts
+  - Sets up progress bar via components/nanobar.html include
   
   Dependencies:
   - seo.html: SEO meta tags and Open Graph data
@@ -22,7 +22,7 @@
   Performance Notes:
   - Scripts loaded in head for immediate availability
   - MathJax loaded asynchronously to prevent render blocking
-  - Nanobar provides visual loading feedback
+  - Nanobar provides visual loading feedback (see components/nanobar.html)
   ===================================================================
 -->
 
@@ -52,29 +52,8 @@
   {% include components/mermaid.html %}
 {% endif %}
 
-<!-- Nano Progress Bar - Visual loading indicator -->
-<script defer src="{{'/assets/js/nanobar.min.js' | relative_url }}"></script>
-
-<!-- Progress Bar Initialization - Creates visual loading feedback -->
-<script>
-    // Wait for DOM to be ready before initializing Nanobar
-    document.addEventListener('DOMContentLoaded', function() {
-        // Check if the progress bar element exists before initializing
-        var progressElement = document.getElementById('top-progress-bar');
-        if (progressElement) {
-            var options = {
-              classname: 'nanobar',
-              id: 'top-progress-bar'
-            };
-            var nanobar = new Nanobar(options);
-            nanobar.go( 30 );  // Initial loading state
-            nanobar.go( 76 );  // Partial completion
-            nanobar.go(100);   // Complete loading
-        } else {
-            console.warn('Progress bar element #top-progress-bar not found. Skipping Nanobar initialization.');
-        }
-    });
-</script>
+<!-- Nano Progress Bar - Visual loading indicator (config-driven) -->
+{% include components/nanobar.html %}
 
 <!-- MathJax - Mathematical notation rendering (async; bundled under assets/vendor) -->
 <script id="MathJax-script" async src="{{ '/assets/vendor/mathjax/es5/tex-mml-chtml.js' | relative_url }}"></script>

data/_includes/core/header.html

@@ -30,7 +30,10 @@
   - ARIA labels for screen readers
   - Focus management for offcanvas
   
-  TODO: Fix Nanobar progress bar positioning and animation
+  Nanobar:
+  - Configured via `site.nanobar.*` in _config.yml
+  - When `position: navbar`, the bar mounts inside `#top-progress-target` below
+  - Otherwise it floats fixed to the viewport (top or bottom)
   ===================================================================
 -->
 
@@ -48,15 +51,7 @@
     <!-- TOP NAVIGATION BAR              -->
     <!-- ================================ -->
     <div class="navbar navbar-expand-lg bg-body-tertiary flex-nowrap justify-content-center bottom-shadow">
-       
-        <!-- ========================== -->
-        <!-- PROGRESS BAR INDICATOR    -->
-        <!-- ========================== -->
-        <!-- Fixed position progress bar for page loading feedback -->
-        <div class="nanobar" id="top-progress-bar" style="position: fixed;" role="progressbar" aria-label="Page loading progress" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">
-            <div class="bar"></div>
-        </div>
-        
+
         <!-- ========================== -->
         <!-- MAIN NAVIGATION CONTAINER -->
         <!-- ========================== -->
@@ -186,4 +181,15 @@
             </div>
         </nav>
     </div>
+
+    <!-- ========================== -->
+    <!-- PROGRESS BAR MOUNT POINT  -->
+    <!-- ========================== -->
+    <!-- Nanobar mounts here when site.nanobar.position == "navbar" so the bar
+         renders as a thin strip directly under the header. For "top" / "bottom"
+         the bar floats fixed to the viewport and no mount is needed. -->
+    {%- assign _nb_pos = site.nanobar.position | default: "top" -%}
+    {%- if site.nanobar.enabled != false and _nb_pos == "navbar" -%}
+    <div id="top-progress-target" class="nanobar-mount" aria-hidden="true"></div>
+    {%- endif -%}
 </header>

data/_includes/navigation/navbar.html

@@ -38,6 +38,7 @@
 
               {%- for link in nav_main -%}
                 {%- assign has_children = link.children and link.children.size > 0 -%}
+                {%- assign items_remaining = nav_main.size | minus: forloop.index -%}
 
                 {%- if has_children -%}
                     <li class="nav-item dropdown d-flex align-items-center nav-hover-dropdown" role="none">
@@ -69,7 +70,7 @@
                             <span class="visually-hidden">Toggle {{ link.title }} submenu</span>
                         </button>
 
-                        <ul class="dropdown-menu dropdown-menu-start" aria-labelledby="dropdown-{{ link.title | slugify }}" role="menu">
+                        <ul class="dropdown-menu {% if items_remaining < 2 %}dropdown-menu-end{% else %}dropdown-menu-start{% endif %}" aria-labelledby="dropdown-{{ link.title | slugify }}" role="menu">
                             {%- for child in link.children -%}
                                 <li role="none">
                                     <a

data/_layouts/landing.html

@@ -66,26 +66,32 @@ layout: root
                 </div>
             </div>
             <div class="col-lg-6 text-center order-2">
+                {%- comment -%}
+                  Inline `aspect-ratio` + `max-width` reserve the final box size BEFORE
+                  external CSS parses, eliminating the post-load "jerk" caused by the
+                  vendored Bootstrap `.ratio` class loading after first paint.
+                {%- endcomment -%}
                 {% if page.hero_image %}
-                <div class="landing-hero-media ratio ratio-4x3 mx-auto shadow-lg rounded overflow-hidden">
+                <div class="landing-hero-media mx-auto shadow-lg rounded overflow-hidden"
+                     style="aspect-ratio: 4 / 3; max-width: min(100%, 28rem); width: 100%;">
                     <img
                         src="{{ page.hero_image | relative_url }}"
                         alt="{{ page.title }}"
-                        class="w-100 h-100"
+                        class="landing-hero-img w-100 h-100"
                         width="800"
                         height="600"
                         loading="eager"
                         decoding="async"
                         fetchpriority="high"
-                        style="object-fit: contain;"
+                        onload="this.classList.add('is-loaded')"
+                        style="object-fit: contain; display: block;"
                     >
                 </div>
                 {% else %}
-                <div class="landing-hero-media ratio ratio-4x3 mx-auto shadow-lg rounded overflow-hidden">
-                    <div class="position-absolute top-0 start-0 w-100 h-100 d-flex flex-column align-items-center justify-content-center bg-secondary bg-opacity-25 text-body rounded">
-                        <i class="bi bi-code-square display-1"></i>
-                        <p class="mt-3 mb-0 px-3">Jekyll Theme</p>
-                    </div>
+                <div class="landing-hero-media mx-auto shadow-lg rounded overflow-hidden d-flex flex-column align-items-center justify-content-center bg-secondary bg-opacity-25 text-body"
+                     style="aspect-ratio: 4 / 3; max-width: min(100%, 28rem); width: 100%;">
+                    <i class="bi bi-code-square display-1"></i>
+                    <p class="mt-3 mb-0 px-3">Jekyll Theme</p>
                 </div>
                 {% endif %}
             </div>

data/_sass/core/_navbar.scss

@@ -367,6 +367,12 @@
     box-shadow: 0 0.5rem 1.5rem rgba(0, 0, 0, 0.175);
     border: 1px solid var(--bs-border-color-translucent);
   }
+
+  // Right-align dropdowns near the end of the nav to prevent overflow clipping
+  .nav-hover-dropdown > .dropdown-menu.dropdown-menu-end {
+    left: auto;
+    right: 0;
+  }
   
   // Smooth hover reveal animation
   .nav-hover-dropdown .dropdown-menu {

data/_sass/custom.scss

@@ -40,20 +40,33 @@ html, body {
     min-height: 50vh;
 }
 
-// Landing layout: stable hero media slot (ratio) + no reliance on scroll script for first paint
+// Landing layout: stable hero media slot (CSS aspect-ratio) + smooth image fade-in.
+// The inline `aspect-ratio` + `max-width` on .landing-hero-media in landing.html
+// reserve the box size before this stylesheet loads — these rules are progressive
+// enhancement on top of that.
 .landing-hero {
     .landing-hero-media {
         max-width: min(100%, 28rem);
+        // Subtle background while the image streams in so the box isn't a flash of
+        // empty colored space against the hero gradient.
+        background-color: rgba(255, 255, 255, 0.06);
     }
 
-    .landing-hero-media.ratio > img {
+    .landing-hero-img {
         object-position: center;
+        opacity: 0;
+        transition: opacity 0.45s ease-out;
+
+        &.is-loaded {
+            opacity: 1;
+        }
     }
 }
 
 @media (prefers-reduced-motion: reduce) {
-    .landing-hero .landing-hero-media {
+    .landing-hero .landing-hero-img {
         transition: none;
+        opacity: 1;
     }
 }
 
@@ -170,9 +183,51 @@ html, body {
     height: 56px;
 }
 
-// Cookie banner: above fixed navbar (1030), below offcanvas (1045) so drawers cover it
+// Cookie banner: above fixed navbar (1030), below offcanvas (1045) so drawers cover it.
+// Show/hide is driven by:
+//   - `[hidden]` attribute on initial render and after dismissal (no layout cost)
+//   - `.cookie-banner-visible` class to slide / fade into view
 .cookie-consent-banner {
     z-index: 1036;
+    background: linear-gradient(135deg, #2c3e50 0%, #3498db 100%);
+    backdrop-filter: blur(10px);
+    border-top: 1px solid rgba(255, 255, 255, 0.1);
+
+    // Off-screen + transparent until JS adds .cookie-banner-visible.
+    // Using `transform` + `opacity` (and NOT `display: none`) keeps the transition smooth.
+    opacity: 0;
+    transform: translateY(100%);
+    transition: transform 0.4s cubic-bezier(0.4, 0, 0.2, 1),
+                opacity   0.35s cubic-bezier(0.4, 0, 0.2, 1);
+    will-change: transform, opacity;
+
+    // The `hidden` attribute (set in markup + after dismissal) removes the banner
+    // from the layout entirely so it can't intercept clicks while invisible.
+    &[hidden] {
+        display: none !important;
+    }
+
+    &.cookie-banner-visible {
+        opacity: 1;
+        transform: translateY(0);
+    }
+
+    @media (max-width: 768px) {
+        .btn {
+            width: 100%;
+            margin-bottom: 0.5rem;
+
+            &:last-child {
+                margin-bottom: 0;
+            }
+        }
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .cookie-consent-banner {
+        transition: none;
+    }
 }
 
 // Active TOC link highlighting

data/assets/js/nanobar-init.js

@@ -0,0 +1,63 @@
+/**
+ * Nanobar Initialization — config-driven page-load progress bar.
+ *
+ * Reads settings from `window.zer0Nanobar` (injected by the
+ * _includes/components/nanobar.html Liquid template) and instantiates the
+ * Nanobar library that was loaded via <script defer>.
+ *
+ * Placement modes (site.nanobar.position):
+ *   "top"    – fixed bar at the top of the viewport (default)
+ *   "bottom" – fixed bar at the bottom of the viewport
+ *   "navbar" – inline strip mounted inside #top-progress-target under header
+ *
+ * @see _config.yml  → nanobar section
+ * @see _includes/components/nanobar.html
+ * @see _includes/core/header.html → #top-progress-target mount point
+ */
+(function () {
+  'use strict';
+
+  document.addEventListener('DOMContentLoaded', function () {
+    if (typeof Nanobar !== 'function') { return; }
+
+    var cfg = window.zer0Nanobar || {};
+    var classname = cfg.classname || 'nanobar';
+
+    // ----- Resolve mount target -----
+    // Priority: explicit selector → position "navbar" → none (fixed to viewport)
+    var targetEl = null;
+    if (cfg.target) {
+      targetEl = document.querySelector(cfg.target);
+    } else if (cfg.position === 'navbar') {
+      targetEl = document.getElementById('top-progress-target');
+    }
+
+    // ----- Position modifier class -----
+    var positionMod = '';
+    if (cfg.position === 'bottom') { positionMod = classname + '--bottom'; }
+    if (cfg.position === 'navbar') { positionMod = classname + '--navbar'; }
+
+    // ----- Create the Nanobar instance -----
+    var nanobar = new Nanobar({
+      classname: classname,
+      id: cfg.id,
+      target: targetEl || undefined
+    });
+
+    if (positionMod && nanobar.el && nanobar.el.classList) {
+      nanobar.el.classList.add(positionMod);
+    }
+
+    // ----- Animate progress steps -----
+    var steps = (cfg.steps && cfg.steps.length) ? cfg.steps : [30, 76, 100];
+    var delay = cfg.stepDelay || 0;
+
+    if (delay > 0) {
+      steps.forEach(function (pct, i) {
+        setTimeout(function () { nanobar.go(pct); }, i * delay);
+      });
+    } else {
+      steps.forEach(function (pct) { nanobar.go(pct); });
+    }
+  });
+})();

data/scripts/generate-roadmap.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# generate-roadmap.rb
+# =============================================================================
+#
+# Reads `_data/roadmap.yml` and updates the README.md roadmap section in-place.
+#
+# It rewrites two regions delimited by HTML comment markers:
+#
+#   <!-- ROADMAP_MERMAID:START -->  ...  <!-- ROADMAP_MERMAID:END -->
+#   <!-- ROADMAP_TABLE:START -->    ...  <!-- ROADMAP_TABLE:END -->
+#
+# Usage:
+#   ruby scripts/generate-roadmap.rb              # update README.md in place
+#   ruby scripts/generate-roadmap.rb --check      # exit non-zero if README is stale
+#   ruby scripts/generate-roadmap.rb --stdout     # print regenerated sections only
+#
+# This script has no gem dependencies beyond the Ruby stdlib.
+# =============================================================================
+
+require 'yaml'
+require 'date'
+require 'optparse'
+
+ROOT       = File.expand_path('..', __dir__)
+DATA_FILE  = File.join(ROOT, '_data', 'roadmap.yml')
+README     = File.join(ROOT, 'README.md')
+
+MERMAID_START = '<!-- ROADMAP_MERMAID:START -->'
+MERMAID_END   = '<!-- ROADMAP_MERMAID:END -->'
+TABLE_START   = '<!-- ROADMAP_TABLE:START -->'
+TABLE_END     = '<!-- ROADMAP_TABLE:END -->'
+
+# Width used to right-pad the gantt label column so the `:status, start, end`
+# tail aligns vertically. Adjust if very long version/title combinations show up.
+GANTT_LABEL_WIDTH = 28
+
+# ---------------------------------------------------------------------------
+# Rendering helpers
+# ---------------------------------------------------------------------------
+
+# Mermaid gantt task line for a single milestone.
+#
+#   v0.22 AIEO Optimization :active, 2026-03, 2026-04
+#   v1.0  Stable Release    :milestone, 2027-01, 1d
+#
+def gantt_task(milestone)
+  label   = "v#{milestone['version']} #{milestone['title']}"
+  status  = milestone['status'].to_s
+  start   = milestone['start']
+  finish  = milestone['end'] || milestone['start']
+
+  prefix =
+    case status
+    when 'completed' then 'done, '
+    when 'active'    then 'active, '
+    when 'milestone' then 'milestone, '
+    else ''
+    end
+
+  range = status == 'milestone' ? "#{start}, 1d" : "#{start}, #{finish}"
+  "    #{label.ljust(GANTT_LABEL_WIDTH)} :#{prefix}#{range}"
+end
+
+def render_mermaid(data)
+  title      = data.dig('meta', 'title') || 'zer0-mistakes Roadmap'
+  milestones = data['milestones'] || []
+
+  # Group by section while preserving the order in which sections first appear.
+  sections = milestones.group_by { |m| m['section'] || 'Roadmap' }
+  ordered  = milestones.map { |m| m['section'] }.uniq
+
+  lines = []
+  lines << '```mermaid'
+  lines << 'gantt'
+  lines << "    title #{title}"
+  lines << '    dateFormat YYYY-MM'
+  ordered.each do |section|
+    lines << "    section #{section}"
+    sections[section].each { |m| lines << gantt_task(m) }
+  end
+  lines << '```'
+  lines.join("\n")
+end
+
+# Status → human-readable target column for the summary table.
+def target_label(milestone)
+  case milestone['status']
+  when 'completed'
+    if (released = milestone['released'])
+      Date.parse(released.to_s).strftime('%b %Y')
+    else
+      'Completed'
+    end
+  when 'active'
+    milestone['target'] || 'In progress'
+  when 'milestone', 'planned'
+    milestone['target'] || milestone['start']
+  else
+    milestone['target'] || ''
+  end
+end
+
+def render_table(data)
+  rows = (data['milestones'] || []).map do |m|
+    version  = "**v#{m['version']}**"
+    target   = target_label(m)
+    summary  = m['summary'] || ''
+    status_emoji =
+      case m['status']
+      when 'completed' then '✅ Completed'
+      when 'active'    then '🚧 In Progress'
+      when 'milestone' then '🎯 Milestone'
+      else                  '🗓 Planned'
+      end
+    "| #{version} | #{status_emoji} | #{target} | #{summary} |"
+  end
+
+  header = [
+    '| Version | Status | Target | Highlights |',
+    '|---------|--------|--------|------------|'
+  ]
+
+  (header + rows).join("\n")
+end
+
+def replace_block(content, marker_start, marker_end, replacement)
+  pattern = /(#{Regexp.escape(marker_start)})(.*?)(#{Regexp.escape(marker_end)})/m
+  unless content.match?(pattern)
+    raise "Markers not found in README: #{marker_start} ... #{marker_end}"
+  end
+
+  # Surround the replacement with blank lines so kramdown parses the following
+  # markdown (especially tables) instead of treating it as part of the HTML
+  # comment block. Without the blank line after `<!-- ... -->`, GFM tables
+  # collapse into a single paragraph.
+  content.sub(pattern, "\\1\n\n#{replacement}\n\n\\3")
+end
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main
+  options = { mode: :write }
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: generate-roadmap.rb [--check|--stdout]'
+    opts.on('--check', 'Exit non-zero if README would change') { options[:mode] = :check }
+    opts.on('--stdout', 'Print regenerated sections to stdout') { options[:mode] = :stdout }
+  end.parse!
+
+  # The roadmap data only contains scalars and Date values; Symbol is not used,
+  # but Date/Time must be permitted because YAML's safe loader rejects them by default.
+  # Ruby >= 3.1 supports `permitted_classes:` on `YAML.load_file`. On older Rubies
+  # (e.g. macOS system Ruby 2.6), fall back to `safe_load` which accepted the
+  # keyword earlier, so the generator works for contributors without rbenv/rvm.
+  data =
+    begin
+      YAML.load_file(DATA_FILE, permitted_classes: [Date, Time])
+    rescue ArgumentError
+      YAML.safe_load(File.read(DATA_FILE), permitted_classes: [Date, Time], aliases: false)
+    end
+  mermaid = render_mermaid(data)
+  table   = render_table(data)
+
+  if options[:mode] == :stdout
+    puts mermaid
+    puts
+    puts table
+    return 0
+  end
+
+  original = File.read(README)
+  updated  = original.dup
+  updated  = replace_block(updated, MERMAID_START, MERMAID_END, mermaid)
+  updated  = replace_block(updated, TABLE_START,   TABLE_END,   table)
+
+  if options[:mode] == :check
+    if original == updated
+      puts '✓ README.md roadmap section is up to date with _data/roadmap.yml'
+      return 0
+    else
+      warn '✗ README.md roadmap section is out of date with _data/roadmap.yml'
+      warn '  Run: ./scripts/generate-roadmap.sh'
+      return 1
+    end
+  end
+
+  if original == updated
+    puts 'README.md roadmap section already up to date.'
+  else
+    File.write(README, updated)
+    puts "Updated README.md roadmap section from #{File.basename(DATA_FILE)}."
+  end
+  0
+end
+
+exit main if $PROGRAM_NAME == __FILE__