jekyll-theme-zer0 1.30.0 → 1.31.0

data/_sass/core/_navbar.scss

@@ -6,10 +6,12 @@
 // Breakpoints:
 //   - Desktop >= 992px (inline nav; label density via @container bd-nav)
 //   - Mobile < 992px (offcanvas)
-// Nav label tiers (center track / bd-nav container width):
+// Nav label tiers (center track / bd-nav container width) — TWO, never truncating:
 //   - >= 51rem (~816px): icon + full label
-//   - 41-50.99rem: label only (icons dropped so the labels still fit)
-//   - < 41rem (~656px): icon-only (tooltips on lg–xl viewports)
+//   - < 51rem: icon-only (tooltips on lg–xl viewports)
+// Icons are present in BOTH tiers. The old bare-label middle tier and the
+// `text-overflow: ellipsis` safety net were removed in #405 — a truncated
+// label ("Quicksta…") is worse than an icon with a tooltip.
 // ==============================================================================
 
 // -----------------------------------------------------------------------------
@@ -92,6 +94,20 @@
   }
 }
 
+// The below-lg menu toggle carries a visible "Menu" label beside its glyph, so
+// it cannot be confused with the sidebar hamburger sitting next to it (#405).
+.navbar-toggler.navbar-toggler-labeled {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  width: auto;
+
+  .navbar-toggler-text {
+    font-size: 0.9375rem;
+    line-height: 1;
+  }
+}
+
 // Shared icon-only nav styling (applied via @container bd-nav below)
 @mixin navbar-nav-icon-only {
   #bdNavbar .nav-link .nav-link-text {
@@ -396,16 +412,29 @@
     transform: rotate(180deg);
   }
 
-  // Label density degrades in three tiers, measured on the center track
-  // (the `bd-nav` container), so items fit instead of ellipsizing:
+  // Label density has TWO tiers, measured on the center track (the `bd-nav`
+  // container), so items either fit whole or drop to icons — never truncate:
   //   >= 51rem (816px)   icon + label      — the roomy default
-  //   41-50.99rem        label only        — icons dropped to buy ~20px/item
-  //   < 41rem (656px)    icon only         — labels no longer fit at all
-  // Each boundary is the MEASURED width the tier below it needs for the
-  // theme's seven demo items (815px with icons, 647px without), so a tier only
-  // engages once its own content fits. Items keep min-width:0 + ellipsis as the
-  // last-resort safety net for consumers with more or longer entries.
-  @container bd-nav (min-width: 41rem) {
+  //   < 51rem            icon only         — icon + label no longer fits
+  // 51rem is the MEASURED width the icon+label row needs for the theme's seven
+  // demo items (815px), so the upper tier engages exactly when its own content
+  // fits and the lower one takes over otherwise.
+  //
+  // There used to be a middle 41-50.99rem tier that dropped the ICONS to buy
+  // ~20px per item, plus `text-overflow: ellipsis` as a last-resort safety net.
+  // Both are gone (#405): the ellipsis produced "Quicksta…", and a clipped
+  // label is worse than an icon with a tooltip — the icon is at least honest
+  // about being an abbreviation. Icons now survive at every tier, and the
+  // icon-only cutoff moved 41rem -> 51rem to take over the band the middle
+  // tier used to hold. That is a deliberate behaviour change at 656-816px of
+  // center track: those widths used to show bare labels and now show icons,
+  // with `.nav-tooltip` (992-1199px) carrying the name on hover.
+  //
+  // Consumers with materially more (or longer) items than the theme's seven
+  // demo entries can exceed 51rem of content; with shrink and ellipsis both
+  // removed, the row overflows rather than truncates. A container query
+  // cannot measure content, so raise the boundary below if that happens.
+  @container bd-nav (min-width: 51rem) {
     #bdNavbar .navbar-nav {
       gap: 0.125rem;
     }
@@ -414,28 +443,34 @@
       padding: 0.375rem;
     }
 
+    // No `overflow: hidden` / `text-overflow: ellipsis` here: this tier only
+    // engages once the whole icon+label row fits, so a clipped label would be
+    // a bug rather than a fallback. Labels stay whole or the row goes
+    // icon-only (#405).
     #bdNavbar .nav-link .nav-link-text {
       display: inline !important;
       margin-left: 0;
       min-width: 0;
-      overflow: hidden;
-      text-overflow: ellipsis;
       white-space: nowrap;
       transition: opacity 0.15s ease-in-out;
     }
 
+    // Items do NOT shrink in this tier. Shrinking is what produced the
+    // clipped label this tier removes: the tier only engages once the full
+    // icon+label row fits, so an item that shrinks here is being cut for no
+    // reason.
     #bdNavbar .nav-item,
     #bdNavbar .nav-hover-dropdown {
-      flex: 0 1 auto;
+      flex: 0 0 auto;
       min-width: 0;
     }
 
     #bdNavbar .nav-item > .nav-link:not(.dropdown-toggle-split),
     #bdNavbar .nav-hover-dropdown > .nav-link:first-child {
-      flex: 1 1 auto;
+      flex: 0 0 auto;
       min-width: 0;
       max-width: 100%;
-      overflow: hidden;
+      overflow: visible;
       gap: 0.25rem;
     }
 
@@ -444,52 +479,69 @@
       font-size: 1rem;
     }
 
-    #bdNavbar .nav-link:hover {
+    // Hover lives on the ROW, not on each control. With the chevron overlaying
+    // the link's padding box (below), a per-control background would light
+    // only half the row as the pointer crossed it.
+    #bdNavbar .nav-item:not(.nav-hover-dropdown) > .nav-link:hover,
+    #bdNavbar .nav-hover-dropdown:hover > .nav-link:first-child {
       background-color: var(--bs-tertiary-bg);
       border-radius: 0.375rem;
     }
 
-    .nav-hover-dropdown > .nav-link {
-      border-top-right-radius: 0;
-      border-bottom-right-radius: 0;
-    }
-
-    .nav-hover-dropdown > .dropdown-toggle-split {
-      border-top-left-radius: 0;
-      border-bottom-left-radius: 0;
-      min-width: 1.25rem;
-      min-height: 0;
-      width: 1.25rem;
-      padding-left: 0;
-      padding-right: 0;
-      margin-left: 0 !important;
-    }
-  }
-
-  // Middle tier — the labels fit but the icons no longer do. Dropping the
-  // decorative icon (the label is the accessible name) and tightening the
-  // chevron buys back roughly 20px per item, which is the difference between
-  // "Notebooks" and "N…" at 992-1200px viewports.
-  @container bd-nav (min-width: 41rem) and (max-width: 50.99rem) {
-    #bdNavbar .nav-link i {
-      display: none;
+    // Chevron merged into the parent link's box (#405). It stays a real
+    // <button> — keyboard reachable, `aria-expanded`/`aria-haspopup` intact —
+    // and is only repositioned: absolutely placed over the right end of the
+    // link's padding, which the link reserves with extra padding-right. There
+    // is no longer a gap between the two, so the dead zone between label and
+    // chevron is gone and the whole row is one hover target.
+    // Every rule below is scoped with #bdNavbar deliberately: the tier's own
+    // `#bdNavbar .nav-link { padding: 0.375rem }` above carries an id, so a
+    // class-only `padding-right` here would lose to it and the chevron would
+    // have no reserved space to sit in.
+    #bdNavbar .nav-hover-dropdown {
+      position: relative;
     }
 
-    #bdNavbar .nav-item > .nav-link:not(.dropdown-toggle-split),
     #bdNavbar .nav-hover-dropdown > .nav-link:first-child {
-      gap: 0;
+      border-radius: 0.375rem;
+      padding-right: 1.25rem;
     }
 
-    // Scoped with #bdNavbar to outrank the shared base rule at the top of this
-    // file, which sets the chevron to 1.5rem.
     #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split {
-      min-width: 1rem;
-      width: 1rem;
+      position: absolute;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      z-index: 1;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.25rem;
+      min-width: 1.25rem;
+      min-height: 0;
+      margin: 0 !important;
+      padding: 0;
+      background-color: transparent;
+      border: 0;
+      border-radius: 0 0.375rem 0.375rem 0;
+    }
+
+    // The overlay must not paint its own hover background — the row already
+    // does. Without this the chevron reads as a separate control again, which
+    // is the whole defect. `!important` because the shared base block at the
+    // top of this file sets the chevron's own hover background with equal
+    // specificity and later source order.
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split:hover,
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split:focus-visible,
+    #bdNavbar .nav-hover-dropdown > .dropdown-toggle-split[aria-expanded="true"] {
+      background-color: transparent !important;
     }
   }
 
-  // Icon-only when the center track is too narrow even for bare labels
-  @container bd-nav (max-width: 40.99rem) {
+  // Icon-only when the center track cannot fit the icon+label row. The
+  // boundary is the complement of the tier above so the two tiers tile the
+  // whole range with no gap.
+  @container bd-nav (max-width: 50.99rem) {
     @include navbar-nav-icon-only;
   }
 }
@@ -1099,8 +1151,7 @@
     align-items: center;
 }
 
-#navbar .site-title-text,
-#navbar .site-subtitle-text {
+#navbar .site-title-text {
     display: inline-block;
 }
 
@@ -1137,9 +1188,28 @@
 
 // Desktop (lg+): 3-column grid — [brand/title | main nav | utilities] so nav cannot paint over Search/Settings
 @media (min-width: 992px) {
+    // Optical centering (#405) WITHOUT breaking the container queries.
+    //
+    // The obvious spelling — `1fr auto 1fr` — is a trap here. Track 2 must stay
+    // a `1fr` (a DEFINITE width): `.bd-navbar-nav-viewport` inside it is
+    // `width: 100%` + `container-type: inline-size`, and that percentage only
+    // resolves against a definite track. Make track 2 `auto` and it becomes
+    // content-sized, size containment hands `bd-nav` a degenerate width, and
+    // EVERY `@container bd-nav` label tier stops firing — the bar collapses to
+    // icon-only at all widths, which is the opposite of what #405 is for.
+    //
+    // So the nav keeps the elastic middle track and the two side tracks are
+    // equalised instead, via a shared floor. Whenever the brand and the
+    // utility cluster both fit inside it (the common case), the side tracks
+    // are the same width and the menubar is centred in the bar, not merely
+    // centred in its own track. The floor is deliberately small so it never
+    // steals the width the label tier needs at 1280px.
     #navbar .navbar-main {
         display: grid !important;
-        grid-template-columns: minmax(0, auto) minmax(0, 1fr) auto;
+        grid-template-columns:
+            minmax(var(--zer0-navbar-side-min, 9rem), auto)
+            minmax(0, 1fr)
+            minmax(var(--zer0-navbar-side-min, 9rem), auto);
         align-items: center;
         column-gap: 0.75rem;
         row-gap: 0.25rem;
@@ -1208,8 +1278,7 @@
         display: none;
     }
 
-    #navbar .site-title,
-    #navbar .site-subtitle {
+    #navbar .site-title {
         flex-shrink: 1;
         min-width: 0;
     }
@@ -1227,15 +1296,6 @@
         max-width: none;
     }
 
-    #navbar .site-subtitle .site-subtitle-text {
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
-        display: inline-block;
-        vertical-align: bottom;
-        max-width: none;
-    }
-
     // Progressive brand degradation (container width, not viewport).
     // The home-link icons add ~108px to the brand cluster, so they only appear
     // once the bar is wide enough to carry them AND the full menubar
@@ -1247,12 +1307,6 @@
         }
     }
 
-    @container navbar-main (max-width: 68rem) {
-        #navbar .site-subtitle {
-            display: none !important;
-        }
-    }
-
     @container navbar-main (max-width: 50rem) {
         #navbar .site-title .site-title-text {
             max-width: 100%;
@@ -1318,6 +1372,19 @@
         height: 2.5rem;
     }
 
+    // The square above is for BARE-GLYPH togglers. The labelled menu toggle
+    // (#405) also carries a "Menu" span, and 2.5rem cannot hold glyph + gap +
+    // label — the text would escape the button box and push the page past the
+    // viewport at every width below lg, which is exactly what makes a
+    // fixed-top bar read as "cut off". `.navbar-toggler-labeled`'s own
+    // `width: auto` loses to the ID selector above on specificity (0,2,0 vs
+    // 1,1,0); re-assert it here, where it outranks.
+    #navbar .navbar-toggler.navbar-toggler-labeled {
+        width: auto;
+        min-width: 2.5rem;
+        flex-shrink: 0;
+    }
+
     #navbar .nav-search-button {
         width: 2.5rem;
         height: 2.5rem;

data/_sass/core/_sidebar-extras.scss

@@ -20,20 +20,8 @@
 
 // MOVED → _sass/layouts/_navbar-extras.scss (token-aware FAB stacking)
 // MOVED → _sass/components/_cookie-banner.scss (token-aware, dark-mode-safe)
-// Retained shim: keep stacked-button responsive sizing inside the banner
-// because it is a banner-internal concern, not a banner-shell concern.
-.cookie-consent-banner {
-    @media (max-width: 768px) {
-        .btn {
-            width: 100%;
-            margin-bottom: 0.5rem;
-
-            &:last-child {
-                margin-bottom: 0;
-            }
-        }
-    }
-}
+// The banner's internal layout (formerly a full-width stacked-button shim
+// here) lives with the shell in _sass/components/_cookie-banner.scss.
 
 // Active TOC link highlighting
 .bd-toc nav a.active {

data/_sass/core/code-copy.scss

@@ -357,14 +357,33 @@ pre.highlight > button:focus {
   opacity: 1;
 }
 
-.button,
-button:not(.copy) {
-  display: inline-block;
-  padding: 0 20px;
-  border-radius: 4px;
-  border: 1px solid #bbb;
-  font-size: 11px;
-  cursor: pointer;
+// Extra actions inside a code block — SCOPED TO THIS COMPONENT (#412).
+//
+// This block used to read `.button, button:not(.copy)` with no scope at all.
+// An element selector in a component partial is a site-wide rule: it restyled
+// EVERY button on a consumer site that was not the theme's own copy button —
+// `padding: 0 20px`, `font-size: 11px`, and a hardcoded `#bbb` border that
+// bypassed the design tokens entirely. At specificity (0,1,1) it also outranked
+// `.btn` and any consumer's own `.my-button`, so escaping it meant a
+// specificity fight rather than a cascade (it-journey#634 had to scope to
+// `.code-block-header .itj-clip-btn` to win). A component partial styles its
+// own component and nothing else.
+//
+// The rule is kept, not deleted: a consumer that adds an action to the header
+// (see the `zer0:code-block-ready` contract in assets/js/code-copy.js) should
+// inherit the copy button's shape instead of arriving unstyled. Values are
+// tokens now, so a skin moves them.
+.code-block-header,
+pre.highlight {
+  > .button,
+  > button:not(.copy) {
+    display: inline-block;
+    padding: 0 var(--zer0-space-3);
+    border-radius: var(--zer0-radius-sm);
+    border: 1px solid var(--zer0-color-border);
+    font-size: var(--zer0-text-sm);
+    cursor: pointer;
+  }
 }
 
 // Non-highlight fenced code blocks

data/assets/css/extension-points-demo.css

@@ -0,0 +1,27 @@
+/* ==========================================================================
+   extension-points-demo.css — a live consumer of the per-page `styles:` hook
+   ==========================================================================
+
+   Loaded ONLY by /docs/customization/extension-points/, through that page's
+   `styles:` frontmatter. Its job is to prove the hook works and to mark the
+   demo action button so the page's own prose can point at it.
+
+   Note what it does NOT have to do: fight a specificity war. Before #412,
+   `_sass/core/code-copy.scss` shipped a bare `button:not(.copy)` rule at
+   specificity (0,1,1), which outranked any single class a consumer could
+   write — so downstream code had to scope to `.code-block-header .my-btn`
+   just to set its own padding. That rule is scoped to the component now, and
+   a plain class is enough again.
+   ========================================================================== */
+
+.zer0-demo-action {
+  background: transparent;
+  color: var(--zer0-color-text-muted);
+  font-family: var(--zer0-font-mono);
+  line-height: 1.8;
+}
+
+.zer0-demo-action:hover,
+.zer0-demo-action:focus-visible {
+  color: inherit;
+}

data/assets/data/wiki-index.json

@@ -142,11 +142,30 @@ sitemap: false
         {%- endif -%}
       {%- endfor -%}
       {%- assign outgoing = outgoing | uniq -%}
+      {%- comment -%}
+        `lastmod` and `description` (#412) — both already on `doc` in this loop,
+        so neither costs a new traversal. A notes/library UI needs them:
+        `lastmod` to sort by recency or show staleness, and `description`
+        because `excerpt` is body-derived while `description` is the AUTHORED
+        subtitle, which is the better card line whenever it exists.
+
+        Source order for the date follows the rest of the theme
+        (_includes/core/head.html, _layouts/article.html): `last_modified_at`,
+        then `lastmod`, then the document's own `date`. Emitted as ISO-8601 via
+        `date_to_xmlschema` so a consumer can sort strings without parsing.
+        Both keys are always present and always defined — `null` when the
+        document carries neither — rather than being conditionally omitted,
+        because a key that sometimes disappears is a worse contract than one
+        that is sometimes null.
+      {%- endcomment -%}
+      {%- assign doc_lastmod = doc.last_modified_at | default: doc.lastmod | default: doc.date -%}
       {
         "title": {{ doc.title | default: basename | jsonify }},
         "basename": {{ basename | jsonify }},
         "url": {{ doc.url | jsonify }},
         "collection": {{ doc.collection | default: nil | jsonify }},
+        "lastmod": {% if doc_lastmod %}{{ doc_lastmod | date_to_xmlschema | jsonify }}{% else %}null{% endif %},
+        "description": {{ doc.description | default: nil | jsonify }},
         "tags": {{ doc.tags | default: empty | jsonify }},
         "categories": {{ doc.categories | default: empty | jsonify }},
         "aliases": {{ aliases | jsonify }},

data/assets/js/auto-hide-nav.js

@@ -34,21 +34,61 @@
         // The measured height is also published as --zer0-header-height so
         // stylesheets (theme or consumer) can align overlays with the real
         // header instead of hard-coding its pixel height.
-        function updateBodyPadding() {
-            const navbarHeight = navbar.offsetHeight;
-            document.body.style.paddingTop = navbarHeight + 'px';
-            document.documentElement.style.setProperty('--zer0-header-height', navbarHeight + 'px');
+        //
+        // Layout is never read synchronously here. Reading navbar.offsetHeight
+        // at DOMContentLoaded (and again on every resize) forced a style +
+        // layout pass while stylesheets were still settling (Lighthouse
+        // "forced reflow", ~233ms per read on a throttled phone). Instead:
+        //   - ResizeObserver delivers the navbar's border-box height after the
+        //     browser's own layout pass, before paint, so the padding still
+        //     lands in the first frame;
+        //   - without ResizeObserver, the read happens in a requestAnimationFrame
+        //     callback, and the write in the frame after it, so a read never
+        //     follows a write in the same pass;
+        //   - the last height is cached and nothing is written when it is
+        //     unchanged.
+        let lastNavbarHeight = -1;
+
+        function applyNavbarHeight(height) {
+            height = Math.round(height);
+            if (height === lastNavbarHeight) return;
+            lastNavbarHeight = height;
+            document.body.style.paddingTop = height + 'px';
+            document.documentElement.style.setProperty('--zer0-header-height', height + 'px');
         }
 
-        // Initial padding setup
-        updateBodyPadding();
-
-        // Update padding on window resize with debounce
-        let resizeTimeout;
-        window.addEventListener('resize', function() {
-            clearTimeout(resizeTimeout);
-            resizeTimeout = setTimeout(updateBodyPadding, 150);
-        }, { passive: true });
+        if (typeof window.ResizeObserver === 'function') {
+            const navbarObserver = new ResizeObserver(function(entries) {
+                const entry = entries[entries.length - 1];
+                const box = entry.borderBoxSize && (entry.borderBoxSize[0] || entry.borderBoxSize);
+                // Layout is already clean inside a ResizeObserver callback, so
+                // the offsetHeight fallback (old engines without borderBoxSize)
+                // does not force a reflow.
+                applyNavbarHeight(box && box.blockSize ? box.blockSize : entry.target.offsetHeight);
+            });
+            navbarObserver.observe(navbar);
+        } else {
+            let measureQueued = false;
+            const measureNavbar = function() {
+                if (measureQueued) return;
+                measureQueued = true;
+                window.requestAnimationFrame(function() {
+                    const height = navbar.offsetHeight; // read
+                    window.requestAnimationFrame(function() {
+                        measureQueued = false;
+                        applyNavbarHeight(height); // write, next frame
+                    });
+                });
+            };
+            measureNavbar();
+
+            // Update padding on window resize with debounce
+            let resizeTimeout;
+            window.addEventListener('resize', function() {
+                clearTimeout(resizeTimeout);
+                resizeTimeout = setTimeout(measureNavbar, 150);
+            }, { passive: true });
+        }
 
         // Enhanced scroll handler with better logic
         function handleScroll() {

data/assets/js/code-copy.js

@@ -1,4 +1,53 @@
 // Feature: ZER0-030
+//
+// CONSUMER CONTRACT — code-block extension points (#412).
+// ------------------------------------------------------
+// `.code-block-header` is built HERE, at runtime, not emitted at build time, so
+// a consumer adding a second action to code blocks has nothing in the markup to
+// hook. Before this contract existed the only route was a `MutationObserver`
+// over `#main-content` plus a guess at the wrapper's shape — and wrapper
+// nesting is exactly what a theme refactor changes, so the guess was one
+// release away from breaking. it-journey#634 got it wrong and silently rendered
+// two buttons on every block (26 across 13) until it added a claim marker.
+//
+// Two ways in, both stable:
+//
+//   document.addEventListener('zer0:code-block-ready', function (e) {
+//     e.detail; // { wrapper, header, pre, code, lang }
+//   });
+//
+//   window.zer0OnCodeBlock(function (detail) { … });   // same shape, REPLAYED
+//
+// The event bubbles from the wrapper, fires exactly once per code block, and is
+// dispatched after the block is fully decorated — line numbers, a11y attributes
+// and the copy button are all in place before a consumer sees it. `header` is
+// null for a standalone `<pre>` outside a Rouge wrapper, which has no header
+// row; `lang` is null when the block declares no language.
+//
+// Because the sweep runs on `DOMContentLoaded`, a listener registered later
+// would miss every block — so `window.__zer0CodeBlocks` holds the detail of
+// every block already processed, and `zer0OnCodeBlock` replays that array
+// before subscribing. Late registration is the NORMAL case for a deferred
+// consumer script, not an edge case.
+//
+// Docs: docs/development/EXTENSION-POINTS.md
+window.__zer0CodeBlocks = window.__zer0CodeBlocks || [];
+
+window.zer0OnCodeBlock = function (listener) {
+  if (typeof listener !== 'function') return function () {};
+  window.__zer0CodeBlocks.forEach(function (detail) {
+    listener(detail);
+  });
+  var handler = function (event) {
+    listener(event.detail);
+  };
+  document.addEventListener('zer0:code-block-ready', handler);
+  // Returned so a consumer can stop listening; harmless to ignore.
+  return function () {
+    document.removeEventListener('zer0:code-block-ready', handler);
+  };
+};
+
 document.addEventListener('DOMContentLoaded', function () {
   var LANG_LABELS = {
     shell: 'bash',
@@ -157,12 +206,18 @@ document.addEventListener('DOMContentLoaded', function () {
       });
     });
 
+    var wrapper;
+    var header = null;
     if (rougeWrapper) {
-      var header = ensureHeader(rougeWrapper, lang);
+      wrapper = rougeWrapper;
+      header = ensureHeader(rougeWrapper, lang);
       header.appendChild(button);
       rougeWrapper.classList.toggle('code-block--single-line', isSingleLine);
       rougeWrapper.closest('.highlighter-rouge').classList.add('has-code-header');
     } else {
+      // A standalone <pre> is its own wrapper and has no header row: the copy
+      // button is positioned against the <pre> itself.
+      wrapper = preElement;
       if (getComputedStyle(preElement).position === 'static') {
         preElement.style.position = 'relative';
       }
@@ -171,5 +226,21 @@ document.addEventListener('DOMContentLoaded', function () {
     }
 
     preElement.classList.add('has-copy-button');
+
+    // Published LAST, so a consumer never sees a half-decorated block. Exactly
+    // once per block: `preElements` is a Set, and the `.copy` guard above makes
+    // a second sweep over the same block a no-op. See the contract at the top.
+    var detail = {
+      wrapper: wrapper,
+      header: header,
+      pre: preElement,
+      code: codeElement,
+      lang: lang
+    };
+    window.__zer0CodeBlocks.push(detail);
+    wrapper.dispatchEvent(new CustomEvent('zer0:code-block-ready', {
+      bubbles: true,
+      detail: detail
+    }));
   });
 });

data/assets/js/extension-points-demo.js

@@ -0,0 +1,48 @@
+// =============================================================================
+// extension-points-demo.js — a live consumer of the theme's extension points
+// =============================================================================
+//
+// Loaded ONLY by /docs/customization/extension-points/, through that page's
+// `scripts:` frontmatter — which makes this file a demonstration of two
+// contracts at once: the per-page script hook that loads it, and the
+// `zer0:code-block-ready` event it subscribes to.
+//
+// It is deliberately the whole pattern in a dozen lines. The point of #412 is
+// that a consumer adding an action to a code block should not need a
+// MutationObserver, a timeout fallback, or a guess at how deeply the theme
+// nests its wrappers — all three of which it-journey#634 had to carry, and the
+// wrapper guess is what silently produced two buttons per block.
+//
+// Copy this shape. `zer0OnCodeBlock` replays the blocks that were decorated
+// before this script ran, then subscribes for any that follow, so it does not
+// matter whether you load early or late.
+// =============================================================================
+(function () {
+  'use strict';
+
+  if (typeof window.zer0OnCodeBlock !== 'function') return;
+
+  window.zer0OnCodeBlock(function (detail) {
+    // A standalone <pre> outside a Rouge wrapper has no header row to hang an
+    // action on. `header` is null there, and that is the documented signal.
+    if (!detail.header) return;
+    if (detail.header.querySelector('.zer0-demo-action')) return;
+
+    var lines = (detail.code.textContent || '').replace(/\n$/, '').split('\n').length;
+
+    var button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'zer0-demo-action';
+    button.textContent = lines + (lines === 1 ? ' line' : ' lines');
+    button.setAttribute(
+      'aria-label',
+      'This ' + (detail.lang || 'code') + ' block has ' + lines + ' lines'
+    );
+    button.addEventListener('click', function () {
+      detail.pre.focus();
+    });
+
+    // Before the copy button, so Copy keeps its place at the end of the row.
+    detail.header.insertBefore(button, detail.header.querySelector('.copy'));
+  });
+})();