mnfst 0.5.163 → 0.5.164

package/lib/manifest.code.js

@@ -1,73 +1,24 @@
 /*  Manifest Code
 /*  By Andrew Matlock under MIT license
 /*  https://manifestx.dev
-/*
-/*  With reference to:
-/*  - highlight.js (https://highlightjs.org)
-/*  - CodeJar       (https://github.com/antonmedv/codejar)
-/*
-/*  Requires Alpine JS (alpinejs.dev) to operate.
-/*
-/*  Public API
-/*  ----------
-/*  <pre x-code>                               Block; auto-detect language
-/*  <pre x-code="javascript">                  Block; explicit language
-/*  <pre x-code="javascript" lines copy>       Line numbers + floating copy button
-/*  <pre x-code="javascript" name="API call">  Adds a header/title bar
-/*  <pre x-code="javascript" collapse>         Collapsed when long; default 20 lines
-/*  <pre x-code="javascript" collapse="10">    Collapsed to first 10 lines
-/*  <pre x-code="javascript" edit>             CodeJar-powered editor
-/*  <pre x-code="html" from="#demo-id">        Content sourced from another element's innerHTML
-/*
-/*  <code x-code="bash">npm i mnfst</code>     Inline; highlighted in place
-/*  <code x-code="bash" copy>npm i mnfst</code>Inline; click-to-copy
-/*
-/*  <div x-code-group>                         Tab strip across direct children with [name]
-/*    <aside class="frame" name="HTML">…       Frame is a tab panel
-/*    <pre x-code="html" name="HTML">…         Code block is a tab panel
-/*    …                                        Children without [name] are always visible
-/*  </div>
 */
 
 // ─── Library loaders ─────────────────────────────────────────────────────────
 
-// Highlight.js loading is a two-mode affair:
-//
-//   Lean mode (preferred):  core.min.js (~8 KB gz) + one language module
-//                           (~2-7 KB gz each, depending on grammar) per
-//                           distinct language on the page. Used when every
-//                           code block declares an explicit language.
-//                           Loaded via ESM dynamic imports from esm.run
-//                           (jsDelivr's CJS→ESM transpiler); the npm
-//                           package's lib/core and lib/languages/* are
-//                           CommonJS-only, so we go through esm.run to
-//                           get browser-native ESM.
-//
-//   Full mode (fallback):   highlight.min.js (~42 KB gz with ~36 common
-//                           languages, IIFE-wrapped). Used when any block
-//                           requests auto-detect (empty/auto x-code value)
-//                           since hljs needs the whole language set to
-//                           pick. Loaded as a classic <script> from
-//                           cdn-release because it's the only build with
-//                           the languages baked in.
-//
-// We decide once on first call by scanning the page. If a later markdown
-// injection introduces an auto-detect block, the next loadHighlightJS()
-// transparently switches to full mode — the prior core load is harmless
-// (hljs is a single global namespace, the full bundle overwrites it).
+// Lean mode: core + one language module per explicit language (via esm.run
+// ESM). Full mode: the whole bundle, used once any block wants auto-detect.
+// Decided on first call; a later auto-detect block flips to full mode
+// (harmless — the full bundle overwrites the single hljs global).
 
 const HLJS_FULL_URL = 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/highlight.min.js';
-// esm.run resolves extension-less specifiers; including ".js" triggers a
-// deprecation warning at module-evaluation time.
+// esm.run resolves extension-less specifiers; ".js" triggers a deprecation warning.
 const HLJS_CORE_URL = 'https://esm.run/highlight.js@11.11.1/lib/core';
 const HLJS_LANG_BASE = 'https://esm.run/highlight.js@11.11.1/lib/languages/';
 
 let hljsCorePromise = null;
 let hljsFullPromise = null;
 const langLoadPromises = new Map();
-// Becomes true once we've committed to the full bundle (any auto-detect
-// block, any language-module load failure). Once flipped, never resets —
-// we keep using the full bundle for the rest of the page lifecycle.
+// Set once we've committed to the full bundle; never resets.
 let usingFullBundle = false;
 
 function injectScript(src) {
@@ -88,12 +39,8 @@ function injectScript(src) {
     });
 }
 
-// Sentinel used by both loaders to detect whether `window.hljs` is already
-// the FULL bundle (which registers ~190 languages) vs the lean core (which
-// starts with very few). Threshold of 50 separates the two reliably —
-// neither the lean core nor any realistic per-language top-up will reach
-// 50 languages before the full bundle does, and the full bundle always
-// ships well above that.
+// Detect whether window.hljs is the full bundle (~190 langs) vs lean core.
+// 50 separates the two reliably.
 function hljsIsFullBundle() {
     return typeof window.hljs?.listLanguages === 'function'
         && window.hljs.listLanguages().length > 50;
@@ -109,25 +56,16 @@ async function loadHighlightFull() {
 }
 
 async function loadHighlightCore() {
-    // Don't downgrade. If the full bundle is already loaded on window.hljs
-    // (because the hero editor — or any other caller — asked for full mode
-    // first), returning the lean core would mean OVERWRITING window.hljs
-    // with a 4-language instance, deleting the full bundle's grammars.
-    // Per-block callers downstream would then re-request languages,
-    // re-fire reactive bumps, and feed an Alpine re-eval loop. Just hand
-    // back the full instance — registerLanguage's "already includes"
-    // check below makes the rest of the lean path a no-op.
+    // Don't downgrade: if the full bundle is already on window.hljs, returning
+    // the lean core would clobber its grammars. Hand back the full instance.
     if (hljsIsFullBundle()) return window.hljs;
     if (hljsCorePromise) return hljsCorePromise;
     hljsCorePromise = import(HLJS_CORE_URL).then(mod => {
-        // esm.run's CJS→ESM shim exposes hljs as the default export. Mirror
-        // it onto window so existing call sites (Alpine evaluator, the hero
-        // editor, etc.) that read `hljs` as a global keep working.
+        // esm.run's CJS→ESM shim exposes hljs as the default export; mirror
+        // onto window for call sites that read `hljs` as a global.
         const hl = mod.default;
         if (!hl) throw new Error('hljs undefined after core ESM import');
-        // Second guard: even after we awaited the dynamic import, the full
-        // bundle may have arrived in the meantime (its <script> tag races
-        // our ESM fetch). Don't clobber it with the lean core.
+        // Guard again: the full bundle's <script> may have raced our ESM fetch.
         if (hljsIsFullBundle()) return window.hljs;
         window.hljs = hl;
         return hl;
@@ -146,9 +84,7 @@ async function registerLanguage(lang) {
     const p = import(`${HLJS_LANG_BASE}${resolved}`)
         .then(mod => { core.registerLanguage(resolved, mod.default); })
         .catch(() => {
-            // If a language module fails to load (typo, network, deprecated
-            // grammar, etc.) the next call will fall back to the full bundle
-            // so the block at least renders with auto-detect.
+            // Module load failed — fall back to the full bundle (auto-detect).
             usingFullBundle = true;
             langLoadPromises.delete(resolved);
         });
@@ -156,18 +92,13 @@ async function registerLanguage(lang) {
     return p;
 }
 
-// Public entry point. Called per code block with the block's requested
-// language (or null/empty for auto-detect). Returns hljs ready to highlight
-// `requestedLang`, or to auto-detect if we're in full mode.
+// Public entry point. Returns hljs ready to highlight `requestedLang` (or to
+// auto-detect in full mode).
 async function loadHighlightJS(requestedLang = null) {
-    // Once we've committed to the full bundle (a prior block needed
-    // auto-detect, or a language module load failed) every subsequent
-    // call funnels through it.
     if (usingFullBundle || hljsFullPromise) return loadHighlightFull();
-    // Plain-text blocks need an hljs instance for the (no-op) highlightInto
-    // call, but must NOT escalate to the full bundle or fetch a module.
+    // Plain-text needs an hljs instance but must not escalate or fetch a module.
     if (PLAINTEXT_LANGS.has((requestedLang || '').toLowerCase())) return loadHighlightCore();
-    // A per-block call asking for auto-detect → escalate.
+    // Per-block auto-detect → escalate.
     if (!requestedLang || requestedLang === 'auto') {
         usingFullBundle = true;
         return loadHighlightFull();
@@ -182,8 +113,7 @@ let codeJarPromise = null;
 async function loadCodeJar() {
     if (typeof window.CodeJar === 'function') return window.CodeJar;
     if (codeJarPromise) return codeJarPromise;
-    // codejar@4.3.0 ships as an ESM-only module. Import dynamically and expose
-    // on window for downstream consumers (e.g. the hero-editor demo).
+    // codejar@4.3.0 is ESM-only; import dynamically and expose on window.
     codeJarPromise = import('https://cdn.jsdelivr.net/npm/codejar@4.3.0/dist/codejar.js')
         .then(mod => {
             window.CodeJar = mod.CodeJar;
@@ -196,8 +126,7 @@ async function loadCodeJar() {
     return codeJarPromise;
 }
 
-// Tell the utilities plugin to ignore code-related classes / elements so its
-// utility-class scanner doesn't fight with hljs's mutations.
+// Ignore code classes/elements in the utilities scanner so it doesn't fight hljs.
 if (window.ManifestUtilities) {
     window.ManifestUtilities.addIgnoredClassPattern(/^hljs/);
     window.ManifestUtilities.addIgnoredClassPattern(/^language-/);
@@ -212,20 +141,15 @@ if (window.ManifestUtilities) {
 
 // ─── Language resolution ─────────────────────────────────────────────────────
 
-// Common shortenings that authors expect to work. highlight.js accepts most of
-// these via its own alias system, but we resolve here so we can short-circuit
-// the supported-language check before calling hljs.
+// Common shortenings; resolved here to short-circuit the supported-language
+// check before calling hljs.
 const LANGUAGE_ALIASES = {
     js: 'javascript', ts: 'typescript', py: 'python', rb: 'ruby',
     sh: 'bash', shell: 'bash', yml: 'yaml', html: 'xml', svg: 'xml'
 };
 
-// Languages that mean "render as plain text — no highlighting." hljs ships a
-// trivial `plaintext` grammar, but there's no point loading a module (or
-// auto-detecting) for content the author explicitly marked plain. `txt` in
-// particular has NO module on the CDN — importing it 404s, and the failed
-// import escalates the whole page to the full bundle. Short-circuiting these
-// keeps the lean path intact and skips the network round-trip entirely.
+// "Render as plain text" languages — no module fetch, no auto-detect. `txt`
+// in particular has no CDN module (a 404 would escalate the page to full mode).
 const PLAINTEXT_LANGS = new Set(['txt', 'text', 'plain', 'plaintext', 'none', 'nohighlight']);
 
 function resolveLanguage(hljs, langAttr) {
@@ -236,18 +160,12 @@ function resolveLanguage(hljs, langAttr) {
 
 // ─── Content prep helpers ────────────────────────────────────────────────────
 
-// Drop any leading/trailing blank lines (including pure-whitespace lines).
-// Authors typically write <pre x-code> on its own line, leaving stray newlines
-// that throw off line numbering and the collapse threshold. Stripping multiple
-// also covers the case where authors leave a blank line before </pre> for
-// readability, which would otherwise render as a visible trailing gap.
+// Drop leading/trailing blank lines (throw off line numbering and collapse).
 function trimWrappingNewlines(text) {
     return text.replace(/^(?:[ \t]*\n)+/, '').replace(/(?:\n[ \t]*)+$/, '');
 }
 
-// Remove the smallest common leading-whitespace block from every non-empty
-// line. Sourced text that came indented under HTML markup looks indented
-// inside the code block too, which is rarely what the author wants.
+// Remove the smallest common leading-whitespace block from every non-empty line.
 function dedent(text) {
     const lines = text.split('\n');
     let minIndent = Infinity;
@@ -266,20 +184,13 @@ function prepSource(raw) {
     return dedent(trimWrappingNewlines(raw));
 }
 
-// Resolve the content for an element, honouring `from="#id"` (which reads the
-// referenced element's innerHTML, preserving HTML markup as the rendered
-// source) before falling back to the host element's own content.
+// Resolve an element's source, honouring `from="#id"` (reads the referenced
+// element's innerHTML) before the host's own content.
 //
-// HTML examples are the special case: authors expect to write the literal
-// markup (`<button>`, `<div>` etc.) without entity-escaping every char. The
-// browser parses those into real DOM nodes inside the <pre>, so textContent
-// would only see "ClickMe" instead of `<button>ClickMe</button>`. Reading
-// innerHTML serialises the DOM back to source text, and a textarea-based
-// decode unwraps any `&lt;`/`&gt;` entities so mixed-style authoring also
-// works. For non-HTML languages we keep textContent — JS/CSS/etc. content
-// rarely contains tags, and innerHTML would re-encode any entities the
-// author DID write back as &lt; (preserving them in the highlighted output
-// as literal text, which is wrong).
+// HTML is the special case: authors write literal markup, so the browser parses
+// it into real DOM nodes — textContent would lose the tags. innerHTML serialises
+// back to source and a textarea decodes entities. Non-HTML keeps textContent
+// (innerHTML would wrongly re-encode any entities the author did write).
 function resolveSource(el) {
     const fromRef = el.getAttribute('from');
     if (fromRef) {
@@ -287,23 +198,16 @@ function resolveSource(el) {
         if (target) return prepSource(target.innerHTML);
     }
     const lang = (el.getAttribute('x-code') || el.getAttribute('language') || '').toLowerCase();
-    // Markdown plugin emits <pre x-code="lang"><code>source</code></pre>. The
-    // <code> body is text-only (entity-escaped HTML decoded by the browser
-    // into a text node), so textContent returns the exact source the author
-    // wrote — preserving valueless attributes (data-tailwind, not
-    // data-tailwind=""), multi-line attribute lists, and other formatting
-    // that an innerHTML round-trip would normalise away.
+    // Markdown emits <pre x-code><code>source</code></pre>. The <code> body is
+    // text-only, so textContent returns the exact author source (preserving
+    // valueless attributes and formatting an innerHTML round-trip would normalise).
     const childCode = el.querySelector(':scope > code');
     if (childCode) {
         return prepSource(childCode.textContent);
     }
-    // Raw HTML case: the author wrote `<pre x-code="html"><div…></div></pre>`
-    // directly in an .html file. Read innerHTML and decode any entities so
-    // mixed-style authoring still works — but valueless attributes will pick
-    // up the browser's `=""` normalisation here, which is unavoidable once
-    // the markup has been parsed into real DOM nodes. Authors who want exact
-    // source preservation should use a fenced markdown block or write the
-    // body as entity-escaped text inside the pre.
+    // Raw HTML written directly in an .html file: read innerHTML and decode
+    // entities. Valueless attributes pick up the browser's `=""` normalisation
+    // here — unavoidable once parsed into DOM nodes.
     if (HTML_LIKE_LANGS.has(lang)) {
         const decoder = document.createElement('textarea');
         decoder.innerHTML = el.innerHTML;
@@ -312,19 +216,15 @@ function resolveSource(el) {
     return prepSource(el.textContent);
 }
 
-// hljs aliases (resolved upstream) map to "xml" internally, but authors may
-// type any of these. Keep them all in the set so the source-reading path
-// behaves the same regardless of the spelling used in the attribute.
+// All map to "xml" internally; kept in one set so source-reading behaves the
+// same regardless of spelling.
 const HTML_LIKE_LANGS = new Set(['html', 'xml', 'svg', 'xhtml', 'rss', 'atom']);
 
 // ─── Highlighting ────────────────────────────────────────────────────────────
 
-// Apply syntax highlighting to a <code> element's textContent. Returns the
-// language hljs actually used (or null when no highlighting was applied), so
-// callers can mark the host element accordingly.
+// Highlight a <code> element. Returns the language hljs used (or null).
 function highlightInto(codeEl, source, hljs, requestedLang) {
-    // Explicit plain text: keep the code-block chrome (hljs base class gives it
-    // the background/padding) but apply no token colours and skip auto-detect.
+    // Explicit plain text: keep the code-block chrome, no token colours.
     if (PLAINTEXT_LANGS.has((requestedLang || '').toLowerCase())) {
         codeEl.textContent = source;
         codeEl.className = 'hljs language-plaintext';
@@ -339,9 +239,8 @@ function highlightInto(codeEl, source, hljs, requestedLang) {
         codeEl.dataset.highlighted = 'yes';
         return lang;
     }
-    // Auto-detect path. Skip when the content looks like HTML markup — hljs
-    // logs a noisy warning for content that contains < and > in close
-    // proximity, which fires constantly on any HTML-fragment example.
+    // Auto-detect. Skip HTML-looking content — hljs logs a noisy warning for
+    // < and > in close proximity.
     codeEl.textContent = source;
     if (!/^[^<]*<\w[^>]*>[^<]*<\/\w/.test(source)) {
         try {
@@ -373,11 +272,8 @@ function setupInlineCopy(el) {
             await navigator.clipboard.writeText(el.textContent);
             el.classList.add('copied');
             setTimeout(() => el.classList.remove('copied'), 1500);
-            // Progressive enhancement: when the tooltip plugin is loaded and
-            // the author hasn't already bound an x-tooltip to this element,
-            // flash the copied-icon in a tooltip as confirmation. Skipped
-            // entirely if either condition isn't met — the .copied class
-            // toggle above is always the baseline feedback.
+            // Progressive enhancement: flash a copied-icon tooltip when the
+            // tooltip plugin is present and no x-tooltip is already bound.
             if (window.ManifestTooltips && typeof window.ManifestTooltips.showTransient === 'function'
                 && !el.hasAttribute('x-tooltip')) {
                 window.ManifestTooltips.showTransient(
@@ -396,19 +292,13 @@ function setupInlineCopy(el) {
 // ─── Block (<pre x-code>) ────────────────────────────────────────────────────
 
 async function setupBlock(pre, hljs) {
-    // Build-once guard. setupBlock can reach this function from two paths
-    // (processCodeElement for standalone, setupCodeGroup for panels) and a
-    // re-entry would read pre.textContent — which now includes the .lines
-    // gutter's "1\n2\n…" — as fresh source, repeatedly prepending the
-    // gutter digits to the code.
+    // Build-once guard — re-entry would read the .lines gutter digits back as source.
     if (pre.dataset.codeBlockBuilt === 'yes') return;
     pre.dataset.codeBlockBuilt = 'yes';
 
     const source = resolveSource(pre);
     const requested = pre.getAttribute('x-code') || pre.getAttribute('language');
 
-    // Reset internal structure. We always rebuild deterministically so the
-    // first call is the only one that lays anything out.
     pre.innerHTML = '';
 
     // ARIA: region + label when titled
@@ -416,10 +306,7 @@ async function setupBlock(pre, hljs) {
     if (title && !pre.hasAttribute('aria-label')) pre.setAttribute('aria-label', title);
     if (!pre.hasAttribute('role')) pre.setAttribute('role', 'region');
 
-    // Title bar — render only when not inside a code-group (the group's tab
-    // strip already shows the [name], so a per-panel title bar would
-    // duplicate it visually). The aria-label is set either way for assistive
-    // tech.
+    // Title bar — skipped inside a code-group (the tab strip already shows [name]).
     const inGroup = !!pre.closest('[x-code-group]');
     if (title && !inGroup) {
         const header = document.createElement('header');
@@ -448,11 +335,8 @@ async function setupBlock(pre, hljs) {
     const actualLang = highlightInto(code, source, hljs, requested);
     pre.appendChild(code);
 
-    // Copy button (floating, top-end). Suppressed when this block is a
-    // panel inside an [x-code-group] — the group itself owns the single
-    // wrapper-level copy button (which targets the active panel) so the
-    // affordance stays at the outermost container's top-end regardless
-    // of which child(ren) carry [copy].
+    // Copy button (floating, top-end). Suppressed inside a group — the group
+    // owns a single wrapper-level copy button targeting the active panel.
     if (pre.hasAttribute('copy') && !inGroup) setupBlockCopy(pre, code);
 
     // Collapse
@@ -487,9 +371,7 @@ function setupCollapse(pre, code) {
     const lineCount = code.textContent.split('\n').length;
     if (lineCount <= collapseAt) return;
 
-    // Expose the threshold to CSS so the max-height matches the visible-line
-    // count exactly. Line-height in our typography is 1.5, so N lines === N
-    // × 1.5em of content height (plus pre padding handled by the selector).
+    // Expose the threshold to CSS for the max-height (line-height is 1.5).
     pre.style.setProperty('--collapse-lines', String(collapseAt));
     pre.setAttribute('data-collapsed', '');
 
@@ -498,10 +380,8 @@ function setupCollapse(pre, code) {
     btn.type = 'button';
     btn.setAttribute('aria-expanded', 'false');
     const hiddenCount = lineCount - collapseAt;
-    // Visual label is locale-safe (no translatable strings) — "+N" reads
-    // universally as "expand to see N more", "−" (U+2212 minus sign) as
-    // "collapse". Screen readers receive an explicit English aria-label
-    // so the action remains intelligible regardless of the visual glyph.
+    // Visual label is locale-safe ("+N" / "−"); screen readers get an explicit
+    // English aria-label.
     const updateLabel = () => {
         const collapsed = pre.hasAttribute('data-collapsed');
         btn.setAttribute('aria-expanded', collapsed ? 'false' : 'true');
@@ -523,8 +403,7 @@ async function setupEditor(pre, code, lang, hljs) {
     try {
         const CodeJar = await loadCodeJar();
         code.setAttribute('contenteditable', 'plaintext-only');
-        // Some browsers (older Safari) don't support plaintext-only — fall back
-        // to plain "true". CodeJar handles paste sanitization either way.
+        // Older Safari lacks plaintext-only — fall back to "true".
         if (code.getAttribute('contenteditable') !== 'plaintext-only' && code.contentEditable !== 'plaintext-only') {
             code.setAttribute('contenteditable', 'true');
         }
@@ -543,12 +422,9 @@ async function setupEditor(pre, code, lang, hljs) {
             indentOn: /[{[(]\s*$|<[a-zA-Z][^<>]*(?<!\/)>$/,
             addClosing: true
         });
-        // CodeJar applies white-space: pre-wrap. Our convention for code blocks
-        // is true no-wrap (lines extend, parent scrolls), so override.
+        // CodeJar applies pre-wrap; our blocks are no-wrap (parent scrolls).
         code.style.whiteSpace = 'pre';
-        // Expose the editor instance on the host so consumers (e.g. the hero
-        // editor) can wire onUpdate / updateCode / save / restore without
-        // re-mounting CodeJar themselves.
+        // Expose the editor instance on the host for consumers (e.g. hero editor).
         pre._codeJar = editor;
         pre.dispatchEvent(new CustomEvent('code:editor-ready', { detail: { editor } }));
     } catch { /* CodeJar load / mount failed — fail silently */ }
@@ -559,16 +435,11 @@ async function setupEditor(pre, code, lang, hljs) {
 // Process one host element. Routes to inline vs block based on tag.
 async function processCodeElement(el) {
     if (el.dataset.codeProcessed === 'yes') return;
-    // Group-owned panels are handled wholesale by setupCodeGroup: each
-    // <pre x-code> sibling is consumed into a <code> child of the new
-    // group wrapper. Skip here so we don't double-process / re-parent.
+    // Group-owned panels are handled wholesale by setupCodeGroup — skip here.
     if (el.parentElement && el.parentElement.hasAttribute('x-code-group')) return;
     el.dataset.codeProcessed = 'yes';
 
     try {
-        // Pass the requested language to the loader so it can stay in lean
-        // mode (core + only this language) when the rest of the page only
-        // uses explicit languages too.
         const requestedLang = el.getAttribute('x-code') || el.getAttribute('language');
         const hljs = await loadHighlightJS(requestedLang);
         const tag = el.tagName;
@@ -595,61 +466,26 @@ async function processCodeElement(el) {
 
 // ─── Code groups (tab strip across [name] siblings) ──────────────────────────
 
-// Build the canonical group structure:
-//
-//   <pre x-code-group>                         ← wrapper coordinates tabs
-//     <header role=tablist>                      (a <div x-code-group> source
-//       <button role=tab>HTML</button>           is normalized to <pre> at
-//       <button role=tab>CSS</button>            process time)
-//     </header>
-//     <pre x-code="html" name=HTML role=tabpanel>...full block...</pre>
-//     <pre x-code="css"  name=CSS  role=tabpanel style="display:none">...</pre>
-//     <aside class=frame name=Preview role=tabpanel style="display:none">...</aside>
-//     <button.copy>                              ← present when wrapper has [copy]
-//   </pre>
-//
-// Each code panel is a full <pre x-code> block with its own line numbers,
-// collapse toggle, editor — i.e. it runs through setupBlock. The wrapper
-// inherits per-panel feature attributes (lines, edit, collapse) to child
-// panels that don't set them, so:
-//
-//   <pre x-code-group lines>
-//     <pre x-code="html" name=HTML>...</pre>
-//     <pre x-code="css"  name=CSS>...</pre>
-//   </pre>
-//
-// behaves as if each child had `lines` written on it directly. Children
-// that DO set the attribute (or set it to a different value, e.g. per-panel
-// collapse="5") win over inheritance.
-//
-// `copy` is NOT inherited — instead, when present on the wrapper, the
-// plugin attaches a single copy button to the wrapper itself that targets
-// whichever panel is currently active. This keeps the button on the
-// element that actually carries the [copy] attribute, and avoids the
-// visual clutter of one button per tab.
+// A <pre|div x-code-group> wrapper coordinates tabs across its [name] children.
+// Each code panel is a full <pre x-code> block run through setupBlock. Feature
+// attrs (lines/edit/collapse) inherit from wrapper to children that don't set
+// them; children that do win. `copy` is NOT inherited — a single wrapper-level
+// copy button targets the active panel instead.
 const GROUP_INHERITABLE_ATTRS = ['lines', 'edit', 'collapse'];
 
 async function setupCodeGroup(group) {
     if (group.dataset.groupProcessed === 'yes') return;
 
-    // A "panel" is any direct child with a [name] — these are tab panels.
-    // Children without [name] are ambient (always visible alongside whichever
-    // panel is active). When nothing is named, the group has no tabs at all
-    // and renders as a borderless wrapper around its (always-visible) kids —
-    // a frame + code pair, for instance, with no title overhead.
+    // Panels are children with [name]; children without are ambient (always
+    // visible). No names → borderless wrapper around its kids, no tabs.
     const sourcePanels = Array.from(group.children).filter(c => c.hasAttribute('name'));
     const ambientChildren = Array.from(group.children).filter(c => !c.hasAttribute('name'));
     if (sourcePanels.length === 0 && ambientChildren.length === 0) return;
-    // Claim the group synchronously so re-entrant callers (the directive +
-    // observer can both arrive before the first call's `await` resolves)
-    // bail out — otherwise the wrapper accumulates duplicate tab strips.
+    // Claim synchronously so re-entrant callers (directive + observer) bail out.
     group.dataset.groupProcessed = 'yes';
 
-    // Inherit feature attributes from wrapper to child <pre x-code> elements
-    // that don't set them. Ambient (unnamed) pres inherit too, so a frame +
-    // code pair in an unnamed group still benefits from group-level [lines]
-    // / [edit] / [collapse]. Run BEFORE setupBlock so the inherited attrs
-    // drive that block's setup.
+    // Inherit feature attributes to child <pre x-code> that don't set them.
+    // Run BEFORE setupBlock so inherited attrs drive its setup.
     const allCodeChildren = [...sourcePanels, ...ambientChildren].filter(c => c.tagName === 'PRE');
     for (const panel of allCodeChildren) {
         for (const attr of GROUP_INHERITABLE_ATTRS) {
@@ -659,9 +495,7 @@ async function setupCodeGroup(group) {
         }
     }
 
-    // Ordered unique tab names. Multiple panels may share a name (e.g. a
-    // frame + a code block co-visible under one tab); each panel is shown
-    // independently when its tab activates.
+    // Ordered unique tab names. Panels may share a name (frame + code co-visible).
     const tabNames = [];
     for (const p of sourcePanels) {
         const n = p.getAttribute('name');
@@ -670,9 +504,8 @@ async function setupCodeGroup(group) {
     const active = tabNames[0];
     const slugify = s => s.replace(/\s+/g, '-').toLowerCase();
 
-    // Preload hljs + every language needed across the group (named panels +
-    // ambient pres) so each block's setupBlock can synchronously highlight
-    // without re-loading.
+    // Preload hljs + every language across the group so each setupBlock can
+    // highlight synchronously.
     const codeLangs = allCodeChildren
         .filter(p => p.hasAttribute('x-code'))
         .map(p => p.getAttribute('x-code'))
@@ -683,12 +516,8 @@ async function setupCodeGroup(group) {
         for (const l of codeLangs.slice(1)) await registerLanguage(l);
     }
 
-    // Normalize wrapper to <pre>. Authors may write <div x-code-group> or
-    // <pre x-code-group>; we always end up with a <pre> for CSS uniformity.
-    // When converting from <div>, transplant children rather than re-creating
-    // — the same <pre x-code> nodes that Alpine has wired up keep their
-    // identity, so subsequent processOne calls (and any author refs into
-    // them) stay valid.
+    // Normalize wrapper to <pre> for CSS uniformity. When converting from
+    // <div>, transplant children so their Alpine-wired identity stays valid.
     let pre;
     if (group.tagName === 'PRE') {
         pre = group;
@@ -701,12 +530,8 @@ async function setupCodeGroup(group) {
     pre.dataset.groupProcessed = 'yes';
     if (!pre.hasAttribute('role')) pre.setAttribute('role', 'region');
 
-    // Run each code child (named or ambient) through setupBlock so it gets
-    // its full feature treatment (line numbers, copy button, collapse,
-    // editor). Frames stay as-is. setupBlock detects the [x-code-group]
-    // ancestor and suppresses the per-panel title bar — the group header
-    // (when present) serves that role; for headerless groups, the pre is
-    // simply rendered without its own title.
+    // Run each code child through setupBlock for full feature treatment.
+    // Frames stay as-is; setupBlock suppresses the per-panel title bar in a group.
     for (const panel of allCodeChildren) {
         if (panel.hasAttribute('x-code')) {
             await setupBlock(panel, hljs);
@@ -714,11 +539,8 @@ async function setupCodeGroup(group) {
         }
     }
 
-    // Header: tab strip when there are multiple named panels, plain title bar
-    // when there's just one, no header at all when nothing is named. Skipping
-    // the header for headerless groups lets authors pair a frame + code block
-    // inside <div x-code-group> with no repetitive "HTML" title — both render
-    // as ambient siblings inside the wrapper.
+    // Header: tab strip for multiple named panels, plain title bar for one,
+    // none when nothing is named.
     const isSingleTab = tabNames.length === 1;
     const isHeaderless = tabNames.length === 0;
     let header = null;
@@ -731,12 +553,8 @@ async function setupCodeGroup(group) {
         header.appendChild(titleEl);
         if (!pre.hasAttribute('aria-label')) pre.setAttribute('aria-label', active);
     } else if (!isHeaderless) {
-        // The role=tablist sits on an inner <div> that holds the tab buttons.
-        // That way the tablist can have its own overflow-x scrolling (when
-        // there are too many tabs to fit) without dragging sibling header
-        // content into the scroll region. CSS targets the inner element via
-        // [role="tablist"]. The unstyle class opts out of the generic tab
-        // bar styling in manifest.form.css; manifest.code.css styles it.
+        // role=tablist on an inner <div> so it can overflow-x scroll on its own.
+        // `unstyle` opts out of manifest.form.css's generic tab styling.
         tablist = document.createElement('div');
         tablist.className = 'unstyle';
         tablist.setAttribute('role', 'tablist');
@@ -774,11 +592,8 @@ async function setupCodeGroup(group) {
     }
     if (header) pre.insertBefore(header, pre.firstChild);
 
-    // Wire ARIA / IDs on each panel. Multi-tab groups get role="tabpanel" with
-    // aria-labelledby pointing at its tab button; single-tab groups keep the
-    // standalone role="region" + aria-label shape (label set on the wrapper
-    // above) so there's no orphan tabpanel without a tablist. Headerless
-    // groups have no tabpanels — every child is ambient.
+    // Wire ARIA / IDs. Multi-tab: role="tabpanel" + aria-labelledby its tab.
+    // Single-tab keeps the region shape (no orphan tabpanel without a tablist).
     sourcePanels.forEach((panel, i) => {
         const name = panel.getAttribute('name');
         panel.id = panel.id || `${slugify(name)}-panel-${i}`;
@@ -791,16 +606,9 @@ async function setupCodeGroup(group) {
         }
     });
 
-    // Wrapper-level copy button. Created when [copy] is on the wrapper OR on
-    // any child panel — the button always lives at the group's top-end so
-    // the affordance is in the same spot regardless of which child carries
-    // [copy]. setupBlock suppresses the per-panel copy button when inside a
-    // group (the inGroup check) so we never duplicate.
-    //
-    // Appended as a direct child of the <pre> (sibling to the header) so it
-    // can be absolutely positioned over the top-end of the wrapper without
-    // competing with the header's own overflow-scroll region. Same
-    // positioning rule as for a standalone <pre x-code copy>.
+    // Wrapper-level copy button — created when [copy] is on the wrapper or any
+    // panel. Appended as a direct child of <pre> so it can position over the
+    // top-end without competing with the header's scroll region.
     const wrapperHasCopy = pre.hasAttribute('copy');
     const anyPanelCopy = [...sourcePanels, ...ambientChildren].some(p => p.hasAttribute('copy'));
     let copyBtn = null;
@@ -810,11 +618,8 @@ async function setupCodeGroup(group) {
         copyBtn.type = 'button';
         copyBtn.setAttribute('aria-label', 'Copy code to clipboard');
         copyBtn.addEventListener('click', async () => {
-            // When multiple panels share the active name (e.g. a paired
-            // frame + code), prefer the <pre x-code> for copy — the source
-            // is what an author wants to take, not the rendered frame's
-            // text content. Headerless groups have no active name, so pick
-            // the first ambient <pre x-code> child instead.
+            // Prefer the <pre x-code> panel for copy (its source, not a frame's
+            // rendered text). Headerless groups pick the first ambient <pre x-code>.
             let activePanel;
             if (isHeaderless) {
                 activePanel = ambientChildren.find(p => p.tagName === 'PRE' && p.hasAttribute('x-code'));
@@ -833,13 +638,9 @@ async function setupCodeGroup(group) {
         pre.appendChild(copyBtn);
     }
 
-    // Visibility toggle. Explicit style.display rather than the [hidden]
-    // attribute, because pre's display:flex from typography.css outweighs
-    // the UA `[hidden] { display: none }` rule. Also flips the copy button
-    // visibility per-tab: when [copy] sits on the wrapper it stays visible
-    // for every tab; when it sits only on individual panels, the button
-    // shows for tabs whose panels carry [copy] and hides for the rest.
-    // Headerless groups have no tabs to switch, so activate() is a no-op.
+    // Visibility toggle via style.display (pre's display:flex outweighs the UA
+    // [hidden] rule). Also flips per-tab copy-button visibility when [copy] is
+    // per-panel rather than on the wrapper.
     let activeName = active;
     function activate(name) {
         activeName = name;
@@ -863,11 +664,8 @@ async function setupCodeGroup(group) {
 
 // ─── Page scan + observation ─────────────────────────────────────────────────
 
-// Markdown emits <pre><code class="language-X">…</code></pre>. Promote these
-// to first-class hosts by setting x-code on the <pre> when we encounter them,
-// so they flow through the same processor as authored <pre x-code> blocks.
-// Accepts either a Document/Element (scans descendants) or a single <pre>
-// element (adopts just that one).
+// Promote markdown's <pre><code class="language-X"> to first-class hosts by
+// setting x-code on the <pre>. Accepts a Document/Element (scans) or one <pre>.
 function adoptMarkdownBlocks(root = document) {
     if (root && root.tagName === 'PRE' && !root.hasAttribute('x-code')) {
         const code = root.querySelector(':scope > code[class*="language-"]');
@@ -892,15 +690,9 @@ function adoptMarkdownBlocks(root = document) {
     }
 }
 
-// Per-element IntersectionObserver — each candidate processes on its own
-// when it scrolls into view. This is important for two reasons:
-//   1. SPA routes that aren't currently visible (display:none from the
-//      router) shouldn't trigger loadHighlightJS for their hidden blocks.
-//      A page-wide scan would scoop them up and an auto-detect block in a
-//      hidden route would push the loader into full-bundle mode even
-//      though the visible route is lean-mode eligible.
-//   2. Long pages with many code blocks don't pay the highlight cost up
-//      front — each block runs hljs only when it nears the viewport.
+// Per-element IntersectionObserver — process each block only when it nears the
+// viewport. Keeps hidden SPA routes from prematurely escalating the loader to
+// full mode, and defers highlight cost on long pages.
 let codeIO = null;
 
 function ensureObserver() {
@@ -908,12 +700,9 @@ function ensureObserver() {
     codeIO = new IntersectionObserver((entries, observer) => {
         for (const entry of entries) {
             if (!entry.isIntersecting) continue;
-            // The router uses display:none to hide inactive SPA routes. There's
-            // a small window during initial Alpine boot where the IO's initial
-            // entry for an element fires as "intersecting" before the router
-            // has applied display:none. checkVisibility() is the source of
-            // truth; if the element is actually hidden, leave it observed so
-            // a future route change re-fires the IO when it becomes visible.
+            // During Alpine boot the IO can fire "intersecting" before the router
+            // applies display:none. checkVisibility() is the source of truth;
+            // if hidden, leave it observed to re-fire on a future route change.
             const t = entry.target;
             if (typeof t.checkVisibility === 'function' && !t.checkVisibility()) continue;
             observer.unobserve(t);
@@ -924,19 +713,14 @@ function ensureObserver() {
 }
 
 function handleVisible(el) {
-    // When any code element in the active route first crosses into view,
-    // eagerly process every currently-visible candidate on the page. This
-    // avoids the "popping" effect of incremental highlighting as the user
-    // scrolls — once hljs is loaded, everything currently on screen gets
-    // styled at once. Below-the-fold and hidden-route candidates stay
-    // observed and process when they later become visible.
+    // Once one block crosses into view, eagerly process every currently-visible
+    // candidate so highlighting doesn't "pop" in during scroll. Below-the-fold
+    // and hidden-route candidates stay observed for later.
     const candidates = document.querySelectorAll(
         '[x-code]:not([data-code-processed]),' +
         '[x-code-group]:not([data-group-processed]),' +
         'pre:not([x-code]):not([data-code-processed]) > code[class*="language-"],' +
-        // Copy-only inline codespans from markdown (`text`{copy}). Skip those
-        // that also carry x-code — they're already covered by the first
-        // selector — and skip <code copy> inside a <pre> (block-level path).
+        // Copy-only inline codespans (`text`{copy}); skip x-code and in-pre ones.
         'code[copy]:not([x-code]):not([data-code-processed]):not(pre > code)'
     );
     // Always include the triggering element (it's already known to be visible).
@@ -959,9 +743,7 @@ function processOne(el) {
         adoptMarkdownBlocks(el.parentElement);
         processCodeElement(el.parentElement);
     } else if (el.tagName === 'CODE' && el.hasAttribute('copy')) {
-        // Copy-only inline codespan (`text`{copy} in markdown) — no x-code,
-        // no highlighting, just wire the click-to-copy handler. Marking it
-        // as processed prevents re-discovery on subsequent scans.
+        // Copy-only inline codespan — just wire click-to-copy.
         if (el.dataset.codeProcessed !== 'yes') {
             el.dataset.codeProcessed = 'yes';
             setupInlineCopy(el);
@@ -969,29 +751,21 @@ function processOne(el) {
     }
 }
 
-// Start observing every candidate in `root` that hasn't already been
-// processed. Idempotent — re-observation of an already-observed element
-// is a no-op per the IntersectionObserver spec. Elements that are already
-// visible at call time are processed immediately, then unobserved — this
-// makes markdown-plugin-injected blocks render synchronously instead of
-// waiting for the next IO callback (which can stall in headless tests
-// and feels laggy for live markdown updates).
+// Observe every unprocessed candidate in `root` (idempotent). Already-visible
+// elements process immediately so markdown-injected blocks render synchronously
+// instead of waiting for the next IO callback.
 function observeAll(root = document) {
     const io = ensureObserver();
     const candidates = [
         ...root.querySelectorAll('[x-code]:not([data-code-processed])'),
         ...root.querySelectorAll('[x-code-group]:not([data-group-processed])'),
         ...root.querySelectorAll('pre:not([x-code]):not([data-code-processed]) > code[class*="language-"]'),
-        // Copy-only inline codespans (no x-code, not inside <pre>) — markdown's
-        // `text`{copy} syntax. These need only the copy handler wired, no
-        // highlighting work.
+        // Copy-only inline codespans (`text`{copy}) — copy handler only.
         ...root.querySelectorAll('code[copy]:not([x-code]):not([data-code-processed]):not(pre > code)')
     ];
     for (const el of candidates) {
         io.observe(el);
-        // Skip the immediate-process shortcut for elements that are hidden
-        // (display:none route panels, off-screen drawers): keep them observed
-        // so they highlight on the next intersection callback when revealed.
+        // Hidden elements stay observed to highlight when later revealed.
         if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) continue;
         io.unobserve(el);
         processOne(el);
@@ -1013,17 +787,14 @@ function registerAlpine() {
     if (window.__manifestCodeDirectivesRegistered) return;
     window.__manifestCodeDirectivesRegistered = true;
 
-    // `x-code="language"` on any element. Alpine fires the callback once
-    // when the element enters its tree. We don't process immediately —
-    // observe instead, so a hidden route's blocks don't run hljs until the
-    // user actually navigates there.
+    // `x-code` on any element — observe rather than process, so hidden routes
+    // don't run hljs until navigated to.
     Alpine.directive('code', (el) => {
         if (el.dataset.codeProcessed === 'yes') return;
         ensureObserver().observe(el);
     });
 
-    // `x-code-group` on a wrapper element; sets up tabs across [name]
-    // children. The wrapper has no expression value.
+    // `x-code-group` wrapper; tabs across [name] children.
     Alpine.directive('code-group', (el) => {
         if (el.dataset.groupProcessed === 'yes') return;
         ensureObserver().observe(el);
@@ -1056,8 +827,7 @@ async function ensureCodePluginInitialized() {
 
 window.ensureCodePluginInitialized = ensureCodePluginInitialized;
 
-// Expose select internals so the markdown plugin and other consumers can hook
-// in without re-implementing the loaders or processors.
+// Expose select internals for the markdown plugin and other consumers.
 window.ManifestCode = {
     loadHighlightJS,
     loadCodeJar,