@bongos/core 1.17.0

package/modules/hall-ui/public/primer.js

@@ -0,0 +1,641 @@
+// primer.js — the primer reader page (V3.R13-followup #406).
+//
+// Fetches /builders/primer.md (canonical markdown from docs/onboarding/),
+// parses it with a small hand-rolled parser covering the subset the primer
+// uses (headings, paragraphs, lists, tables, fenced code, hr, inline
+// **bold** / *italic* / `code` / [link](url)), inlines the five onboarding
+// diagrams at matching sections, builds a TOC from h2s with a scrollspy,
+// drives a top reading-progress bar, and soft-gates the footer ack button
+// until the reader has scrolled past ~90% of the article. Acking POSTs to
+// /api/gds/builders/me/onboarding/primer-read (same endpoint /builder-
+// primer-read uses).
+//
+// No build step. No external markdown dep. The parser is purpose-built for
+// the primer's syntax, not a general-purpose markdown engine — extending it
+// for new constructs is straightforward but should match what the primer
+// actually contains.
+
+(() => {
+  'use strict';
+
+  const API = '/api/gds';
+  const ACK_SCROLL_THRESHOLD = 0.90; // 90% of article scrolled → button enables
+  // V3.R13-followup-2 (#411): the canonical repo on GitHub. Relative file
+  // paths in the primer markdown (../../CLAUDE.md, ../recipes/, etc.) are
+  // rewritten to URLs under these bases so the rendered links go somewhere
+  // useful instead of 404-ing under /builders/*. The bases are NOT hardcoded
+  // here — that would violate the V3.R12 (#236) authorship-attribution audit.
+  // Instead, primer.js fetches /api/gds/public/repo-info at boot; the server
+  // derives the owner/repo at process start from `git remote get-url origin`
+  // (src/bongos/repo-info.js). When the bases are unavailable (network glitch
+  // pre-render, or the server can't reach git), the link rewriter degrades
+  // gracefully — repo-relative hrefs are passed through unchanged so they
+  // 404 instead of crashing the page.
+  let repoBlobBase = null;
+  let repoTreeBase = null;
+
+  // Diagrams to inline at matching h2 sections. The keys are LOWERCASED h2
+  // text (matched as substrings) — keep them tight so the wrong heading
+  // doesn't pick up the wrong picture. The image paths resolve at
+  // /builders/diagrams/* (mounted in server.js).
+  const DIAGRAM_AT_HEADING = [
+    { match: 'two tracks',                  src: '/builders/diagrams/05-two-track-versioning.png', alt: 'The two tracks: product (the game) and internal (the dev system)' },
+    { match: 'claim → ship lifecycle',      src: '/builders/diagrams/01-task-lifecycle.png',       alt: 'The full task lifecycle from backlog through shipped' },
+    { match: 'rank ladder',                 src: '/builders/diagrams/02-rank-ladder.png',          alt: 'The rank ladder — the ranks a builder can hold and how to rise' },
+    { match: 'drachmae and karma',          src: '/builders/diagrams/03-drachmae-karma.png',       alt: 'How the reward currency and karma differ — pay for shipped work vs. reputation signals' },
+    { match: 'get set up',                   src: '/builders/diagrams/04-architecture.png',         alt: 'The complete architecture: your device is just the screen, the dev box holds the worker, the code, and your local memory, the droplet is the authority and production, GitHub holds the repo — and how code travels from the box to prod' },
+  ];
+
+  // -----------------------------------------------------------------------
+  // Tiny utilities
+  // -----------------------------------------------------------------------
+
+  function $(sel) { return document.querySelector(sel); }
+
+  function escapeHtml(s) {
+    return String(s)
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  // Stable slug for heading anchors. Lowercases, strips non-alphanum, joins
+  // with dashes. Matches what most static-site generators do, so anchor
+  // links in the primer's prose ([§foo](#foo)) work the same way.
+  function slugify(text) {
+    return String(text)
+      .toLowerCase()
+      .replace(/[—–]/g, '-')   // em/en dashes
+      .replace(/[^a-z0-9\s-]/g, '')      // strip punctuation
+      .trim()
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-');
+  }
+
+  function toast(msg, type) {
+    // Shared toast mechanism (style.css .toast[data-visible="1"]) — same
+    // data-visible contract OTB.toast uses on pages that load dom-utils.js.
+    const el = $('#toast');
+    if (!el) return;
+    el.textContent = msg;
+    el.dataset.type = type || 'info';
+    el.dataset.visible = '1';
+    clearTimeout(toast._t);
+    toast._t = setTimeout(() => { el.dataset.visible = '0'; }, 3000);
+  }
+
+  // V3.R13-followup-2 (#411): rewrite relative repo paths in primer-markdown
+  // links so they land somewhere usable in the browser rather than 404-ing
+  // under /builders/*. The primer markdown was written for the repo view
+  // (relative paths to other repo files), but it's rendered at
+  // /builders/primer where those paths don't resolve.
+  //
+  // Rules (most-specific first):
+  //   - http(s)://… absolute URL                 → keep as-is
+  //   - #anchor in-page                          → keep as-is
+  //   - 'diagrams/' or 'diagrams'                → /builders/diagrams
+  //     (the diagrams page lives in the hall; trailing slash falls through
+  //     to the game, so we always rewrite to the no-slash form)
+  //   - paths starting with ./ or ../ or any /   → resolve against the
+  //     primer's repo location (docs/onboarding/) and link to GitHub.
+  //     We use the 'blob/main' base for files and 'tree/main' for dirs
+  //     (heuristic: trailing slash or no '.' in basename = dir).
+  //   - anything else                            → keep as-is
+  function resolveLinkHref(href) {
+    if (!href) return href;
+    if (/^https?:\/\//i.test(href)) return href;
+    if (href.startsWith('#')) return href;
+    if (href.startsWith('mailto:') || href.startsWith('tel:')) return href;
+    if (href === 'diagrams/' || href === 'diagrams') return '/builders/diagrams';
+    // task 1472: the drachmae-and-karma doc now has an in-hall reader page, so
+    // keep the reader in the hall instead of bouncing to GitHub. (The repo /
+    // GitHub view still resolves the plain relative link.)
+    if (href === 'drachmae-and-karma.md') return '/builders/drachmae';
+    // The primer.md lives at docs/onboarding/primer.md, so relative paths
+    // resolve against docs/onboarding/.
+    const PRIMER_DIR = 'docs/onboarding/';
+    let resolved;
+    if (href.startsWith('/')) {
+      // Absolute repo path. Strip the leading slash.
+      resolved = href.replace(/^\/+/, '');
+    } else {
+      // Relative. Join with PRIMER_DIR and normalize.
+      resolved = normalizePath(PRIMER_DIR + href);
+    }
+    // Decide blob (file) vs tree (directory). Heuristic: trailing slash =
+    // dir; no '.' in last segment = dir; else file.
+    const trailingSlash = resolved.endsWith('/');
+    const lastSeg = resolved.replace(/\/+$/, '').split('/').pop() || '';
+    const isDir = trailingSlash || !lastSeg.includes('.');
+    const cleanResolved = resolved.replace(/^\/+/, '').replace(/\/+$/, '');
+    const base = isDir ? repoTreeBase : repoBlobBase;
+    // Graceful degradation: if the server-side repo-info fetch failed or
+    // hasn't completed before this render, leave the href as the original
+    // (which 404s harmlessly) rather than producing a broken /undefined/ URL.
+    if (!base) return href;
+    return `${base}/${cleanResolved}`;
+  }
+
+  // Resolve '../' and './' segments in a path. Defensive against edge cases
+  // (no leading slash, repeated slashes); the input is already trusted
+  // because it came from the primer markdown we ship.
+  function normalizePath(p) {
+    const parts = p.split('/');
+    const out = [];
+    for (const part of parts) {
+      if (part === '' || part === '.') continue;
+      if (part === '..') { out.pop(); continue; }
+      out.push(part);
+    }
+    // Preserve a trailing slash if the original had one (matters for the
+    // file/dir heuristic in resolveLinkHref).
+    return out.join('/') + (p.endsWith('/') ? '/' : '');
+  }
+
+  // -----------------------------------------------------------------------
+  // Markdown parser (purpose-built for the primer's subset)
+  //
+  // Block grammar (line-by-line):
+  //   ^# title                       → h1
+  //   ^## section                    → h2
+  //   ^### subsection                → h3
+  //   ^---$                          → hr
+  //   ^```                           → fenced code (closes on next ```)
+  //   ^- item   or  ^[0-9]+\. item   → list (single level)
+  //   ^| col | col |                 → table (separator row '|---|---|' follows)
+  //   blank line                     → paragraph break
+  //   anything else                  → paragraph (run inline)
+  //
+  // Inline grammar (in order; substitution avoids re-matching):
+  //   `code`                         → <code>…</code>
+  //   **bold**                       → <strong>…</strong>
+  //   *italic*                       → <em>…</em>
+  //   [text](url)                    → <a href="url">text</a>
+  // -----------------------------------------------------------------------
+
+  // Inline substitutions. We process them on already-escaped text so we
+  // don't have to defend against html-injection inside literal text — code
+  // spans are escape-safe because the content is the matched group (which
+  // we re-escape). Bold + italic + link use the captured group as-is
+  // (already escaped by the block-level pass).
+  function renderInline(escapedText) {
+    // Code spans first so their contents aren't touched by other rules.
+    // Use a placeholder pass to avoid re-matching.
+    const codeSpans = [];
+    let out = escapedText.replace(/`([^`]+)`/g, (_m, g1) => {
+      codeSpans.push(g1);
+      return `CODE${codeSpans.length - 1}`;
+    });
+    // Links — [text](url). url must be the next paren-group, no nested parens.
+    out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, text, url) => {
+      // url is already html-escaped by the block-level escape; that's fine
+      // for href because we use the raw string and let the browser handle
+      // %-encoding. We strip the quotes that the escape replaced with &quot;.
+      const safeUrl = url.replace(/&amp;/g, '&').replace(/&#39;/g, "'");
+      const resolved = resolveLinkHref(safeUrl);
+      // External (off-instance) links open in a new tab so the reader
+      // doesn't lose their place in the primer.
+      const instApex = location.hostname.split('.').slice(-2).join('.');
+      let linkHost = '';
+      try { linkHost = new URL(resolved, location.href).hostname; } catch (_) { /* relative/opaque href */ }
+      const sameInstance = !!linkHost && (linkHost === location.hostname || linkHost === instApex || linkHost.endsWith('.' + instApex));
+      const external = /^https?:\/\//.test(resolved) && !sameInstance;
+      const attrs = external ? ' target="_blank" rel="noopener"' : '';
+      return `<a href="${escapeHtml(resolved)}"${attrs}>${text}</a>`;
+    });
+    // Bold (run before italic so **x** doesn't match as *(*x*)*).
+    out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+    // Italic.
+    out = out.replace(/(^|[^*])\*([^*]+)\*(?!\*)/g, '$1<em>$2</em>');
+    // Restore code spans.
+    out = out.replace(/CODE(\d+)/g, (_m, idx) => {
+      return `<code>${escapeHtml(codeSpans[Number(idx)])}</code>`;
+    });
+    return out;
+  }
+
+  function parseMarkdown(md) {
+    // Normalize line endings.
+    const lines = String(md).replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    const headings = []; // { level, text, id } — used to build TOC + scrollspy
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      const raw = line;
+
+      // Fenced code block.
+      if (raw.startsWith('```')) {
+        i += 1;
+        const codeLines = [];
+        while (i < lines.length && !lines[i].startsWith('```')) {
+          codeLines.push(lines[i]);
+          i += 1;
+        }
+        i += 1; // consume closing ```
+        out.push(`<pre><code>${escapeHtml(codeLines.join('\n'))}</code></pre>`);
+        continue;
+      }
+
+      // Headings.
+      let hm;
+      if ((hm = raw.match(/^(#{1,3})\s+(.+?)\s*$/))) {
+        const level = hm[1].length;
+        const text = hm[2];
+        const id = slugify(text);
+        headings.push({ level, text, id });
+        out.push(`<h${level} id="${escapeHtml(id)}">${renderInline(escapeHtml(text))}</h${level}>`);
+        i += 1;
+        continue;
+      }
+
+      // Horizontal rule.
+      if (/^---+\s*$/.test(raw)) {
+        out.push('<hr>');
+        i += 1;
+        continue;
+      }
+
+      // Blank line — paragraph separator.
+      if (/^\s*$/.test(raw)) {
+        i += 1;
+        continue;
+      }
+
+      // Table: header row '| ... |' followed by separator row '| --- | --- |'.
+      if (/^\|/.test(raw) && i + 1 < lines.length && /^\|[\s\-:|]+\|\s*$/.test(lines[i + 1])) {
+        const headerCells = splitTableRow(raw);
+        i += 2;
+        const bodyRows = [];
+        while (i < lines.length && /^\|/.test(lines[i])) {
+          bodyRows.push(splitTableRow(lines[i]));
+          i += 1;
+        }
+        let html = '<table><thead><tr>';
+        for (const c of headerCells) html += `<th>${renderInline(escapeHtml(c))}</th>`;
+        html += '</tr></thead><tbody>';
+        for (const row of bodyRows) {
+          html += '<tr>';
+          for (const c of row) html += `<td>${renderInline(escapeHtml(c))}</td>`;
+          html += '</tr>';
+        }
+        html += '</tbody></table>';
+        out.push(html);
+        continue;
+      }
+
+      // Lists (unordered '- ' or ordered '1. '). Single-level; consecutive
+      // list items collapse into one <ul>/<ol>.
+      if (/^(-|\d+\.)\s+/.test(raw)) {
+        const ordered = /^\d+\.\s+/.test(raw);
+        const items = [];
+        while (i < lines.length && /^(-|\d+\.)\s+/.test(lines[i])) {
+          const content = lines[i].replace(/^(-|\d+\.)\s+/, '');
+          items.push(`<li>${renderInline(escapeHtml(content))}</li>`);
+          i += 1;
+        }
+        out.push(`<${ordered ? 'ol' : 'ul'}>${items.join('')}</${ordered ? 'ol' : 'ul'}>`);
+        continue;
+      }
+
+      // Paragraph — collect consecutive non-blank, non-special lines.
+      const paraLines = [raw];
+      i += 1;
+      while (i < lines.length &&
+             !/^\s*$/.test(lines[i]) &&
+             !/^(#{1,3})\s/.test(lines[i]) &&
+             !/^---+\s*$/.test(lines[i]) &&
+             !/^```/.test(lines[i]) &&
+             !/^\|/.test(lines[i]) &&
+             !/^(-|\d+\.)\s+/.test(lines[i])) {
+        paraLines.push(lines[i]);
+        i += 1;
+      }
+      const text = paraLines.join(' ');
+      out.push(`<p>${renderInline(escapeHtml(text))}</p>`);
+    }
+
+    return { html: out.join('\n'), headings };
+  }
+
+  function splitTableRow(line) {
+    // '| a | b | c |' → ['a', 'b', 'c']. Trims, drops the leading/trailing empty cells.
+    const cells = line.split('|').map((c) => c.trim());
+    // Drop the empty strings introduced by the leading/trailing pipes.
+    if (cells.length && cells[0] === '') cells.shift();
+    if (cells.length && cells[cells.length - 1] === '') cells.pop();
+    return cells;
+  }
+
+  // -----------------------------------------------------------------------
+  // Diagram inlining — after the HTML is in the DOM, walk every <h2> and
+  // append a <figure> right after it if the heading matches a known diagram.
+  // -----------------------------------------------------------------------
+
+  function inlineDiagrams(articleEl) {
+    const h2s = articleEl.querySelectorAll('h2');
+    for (const h of h2s) {
+      const txt = h.textContent.toLowerCase();
+      const match = DIAGRAM_AT_HEADING.find((d) => txt.includes(d.match));
+      if (!match) continue;
+      const fig = document.createElement('figure');
+      fig.className = 'primer-figure';
+      const img = document.createElement('img');
+      img.src = match.src;
+      img.alt = match.alt;
+      img.loading = 'lazy';
+      const cap = document.createElement('figcaption');
+      cap.textContent = match.alt;
+      fig.appendChild(img);
+      fig.appendChild(cap);
+      // Place the figure AFTER the h2's first paragraph so it sits inside
+      // the section's flow rather than directly under the heading rule.
+      // Falls back to "right after the h2" if there's no paragraph next.
+      const next = h.nextElementSibling;
+      if (next && next.tagName === 'P') {
+        next.insertAdjacentElement('afterend', fig);
+      } else {
+        h.insertAdjacentElement('afterend', fig);
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // TOC — built from h2 headings.
+  // -----------------------------------------------------------------------
+
+  function renderToc(headings) {
+    const list = $('#primer-toc-list');
+    if (!list) return [];
+    const h2s = headings.filter((h) => h.level === 2);
+    if (h2s.length === 0) {
+      list.innerHTML = '<li class="primer-toc__placeholder">(no sections)</li>';
+      return [];
+    }
+    list.innerHTML = h2s.map((h) =>
+      `<li><a href="#${escapeHtml(h.id)}" data-section="${escapeHtml(h.id)}">${escapeHtml(h.text)}</a></li>`
+    ).join('');
+    return h2s;
+  }
+
+  // -----------------------------------------------------------------------
+  // Scrollspy — highlight the TOC entry for the section the reader is in.
+  //
+  // Behaviour: the "active" section is the LAST h2 whose top has scrolled
+  // past a fixed reading line near the top of the viewport. That way the
+  // active state stays sticky while the reader is in the middle of a
+  // section's paragraphs (not just the brief moment the h2 itself is in
+  // a thin band, which is what an IntersectionObserver with a narrow root-
+  // margin would give us).
+  // -----------------------------------------------------------------------
+
+  function setupScrollspy(tocSections) {
+    if (tocSections.length === 0) return;
+    const links = new Map();
+    for (const a of document.querySelectorAll('.primer-toc__list a')) {
+      links.set(a.dataset.section, a);
+    }
+    if (links.size === 0) return;
+    // Reading line — the y-coordinate (in viewport space) we treat as
+    // "where the reader is looking right now". 100px is well below the
+    // progress bar and any fixed header, and matches where the eye
+    // naturally lands when reading down a page.
+    const READING_LINE_Y = 100;
+    let last = null;
+    function update() {
+      let active = null;
+      for (const s of tocSections) {
+        const el = document.getElementById(s.id);
+        if (!el) continue;
+        if (el.getBoundingClientRect().top <= READING_LINE_Y) {
+          active = s.id;
+        } else {
+          break;
+        }
+      }
+      if (active === last) return;
+      last = active;
+      for (const [id, a] of links) {
+        a.classList.toggle('is-active', id === active);
+      }
+    }
+    window.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update, { passive: true });
+    update();
+  }
+
+  // -----------------------------------------------------------------------
+  // Reading-progress bar — fraction of the article scrolled past.
+  // -----------------------------------------------------------------------
+
+  function setupProgressBar(articleEl, onProgress) {
+    const bar = $('#primer-progress-bar');
+    if (!bar) return;
+    function update() {
+      const rect = articleEl.getBoundingClientRect();
+      const viewport = window.innerHeight || document.documentElement.clientHeight;
+      // 0 when the top of the article is at/below the viewport top;
+      // 1 when the bottom of the article is at/above the viewport top.
+      // We use article.bottom — viewportTop as "how much has scrolled past
+      // me" then normalize by article.height.
+      const total = rect.height + viewport * 0; // article only
+      const scrolled = Math.max(0, -rect.top);
+      const frac = total > 0 ? Math.min(1, scrolled / Math.max(1, rect.height - viewport)) : 0;
+      bar.style.width = `${Math.round(frac * 100)}%`;
+      if (typeof onProgress === 'function') onProgress(frac);
+    }
+    window.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update, { passive: true });
+    update();
+  }
+
+  // -----------------------------------------------------------------------
+  // Footer ack module — soft gate on the 'I have read it' button.
+  // -----------------------------------------------------------------------
+
+  let ackEnabled = false;
+  function setupAck() {
+    const ackSection = $('#primer-ack');
+    const btn = $('#primer-ack-btn');
+    const lede = $('#primer-ack-lede');
+    if (!ackSection || !btn) return;
+    ackSection.hidden = false;
+    btn.addEventListener('click', async () => {
+      if (!ackEnabled || btn.disabled) return;
+      btn.disabled = true;
+      btn.textContent = 'Marking…';
+      try {
+        const resp = await fetch(`${API}/builders/me/onboarding/primer-read`, {
+          method: 'POST',
+          credentials: 'same-origin',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{}',
+        });
+        if (resp.status === 401) {
+          // Not signed in — bounce through the web auth flow and come back.
+          const here = encodeURIComponent(window.location.pathname);
+          window.location.assign(`${API}/auth/web/start?return=${here}`);
+          return;
+        }
+        if (!resp.ok) throw new Error(`primer-read → ${resp.status}`);
+        const data = await resp.json().catch(() => ({}));
+        if (data.already_cleared) {
+          showAckedState('Already acknowledged — you\'re all set.');
+        } else if (data.just_graduated) {
+          showAckedState('Primer acknowledged. You have completed onboarding — welcome.');
+        } else {
+          showAckedState('Primer acknowledged. The work queue is open to you.');
+        }
+        toast('Primer acknowledged.', 'success');
+      } catch (err) {
+        console.error('[primer] ack failed', err);
+        btn.disabled = false;
+        btn.textContent = 'I have read it';
+        toast('Could not mark the primer just now. Try again.', 'error');
+      }
+    });
+  }
+
+  // V3.R13-followup-2 (#411): once acked, hide the button entirely. The
+  // previous design left a washed-out "✓ ACKNOWLEDGED" disabled button in
+  // place which read as clunky. Now: the ack panel collapses to a single
+  // confirmation line + return link, with a subtle check mark.
+  function showAckedState(message) {
+    const btn = $('#primer-ack-btn');
+    const lede = $('#primer-ack-lede');
+    const note = $('#primer-ack-note');
+    const inner = document.querySelector('.primer-ack__inner');
+    if (btn) btn.hidden = true;
+    if (lede) lede.hidden = true;
+    if (inner) inner.classList.add('primer-ack__inner--acked');
+    if (note) {
+      note.hidden = false;
+      note.innerHTML = `<span class="primer-ack__check" aria-hidden="true">✓</span> ${escapeHtml(message)} <a href="/builders">Back to home</a>.`;
+    }
+  }
+
+  function onArticleProgress(frac) {
+    if (frac >= ACK_SCROLL_THRESHOLD && !ackEnabled) {
+      const btn = $('#primer-ack-btn');
+      const lede = $('#primer-ack-lede');
+      if (btn && !btn.dataset.alreadyAcked) {
+        btn.disabled = false;
+        ackEnabled = true;
+      }
+      if (lede) {
+        lede.textContent = 'You have reached the end. The button below is now active.';
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Pre-check: if the builder already has primer_read cleared, render the
+  // ack panel in the already-acknowledged state so the page doesn't
+  // pretend they still need to ack.
+  // -----------------------------------------------------------------------
+
+  async function checkAlreadyAcked() {
+    try {
+      const r = await fetch(`${API}/me`, { credentials: 'same-origin' });
+      if (r.status === 401) return; // anonymous reader; let them read + ack
+      if (!r.ok) return;
+      const data = await r.json();
+      const ob = data.onboarding;
+      if (!ob) return;
+      const cleared = Array.isArray(ob.completed_stages) && ob.completed_stages.includes('primer_read');
+      const past = ob.graduated || (ob.current_stage && ['first_start', 'first_claim', 'first_ship', 'first_vote_received', 'graduated'].includes(ob.current_stage));
+      if (cleared || past) {
+        const btn = $('#primer-ack-btn');
+        if (btn) btn.dataset.alreadyAcked = '1';
+        showAckedState('Already acknowledged — you can re-read the primer any time.');
+      }
+    } catch (_) {
+      // network glitch — let them ack the normal way
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // TOC mobile toggle
+  // -----------------------------------------------------------------------
+
+  function setupTocToggle() {
+    const toc = $('#primer-toc');
+    const btn = $('#primer-toc-toggle');
+    if (!toc || !btn) return;
+    btn.addEventListener('click', () => {
+      const open = toc.classList.toggle('is-open');
+      btn.setAttribute('aria-expanded', open ? 'true' : 'false');
+    });
+    // Close the TOC after a section is picked on mobile.
+    toc.addEventListener('click', (e) => {
+      const a = e.target.closest('a[data-section]');
+      if (!a) return;
+      if (window.matchMedia('(max-width: 760px)').matches) {
+        toc.classList.remove('is-open');
+        btn.setAttribute('aria-expanded', 'false');
+      }
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Boot
+  // -----------------------------------------------------------------------
+
+  // V3.R13-followup-2 (#411): fetch the GitHub URL bases from the server so
+  // they don't have to be hardcoded in this client file (V3.R12 #236 rule).
+  // Fire in parallel with the markdown fetch — both are independent, both
+  // must settle before render. Failure here is non-fatal: resolveLinkHref
+  // gracefully degrades when the bases are null.
+  async function loadRepoInfoBases() {
+    try {
+      const r = await fetch('/api/gds/public/repo-info', { credentials: 'same-origin' });
+      if (!r.ok) return;
+      const data = await r.json();
+      if (data && typeof data.blob_base === 'string') repoBlobBase = data.blob_base;
+      if (data && typeof data.tree_base === 'string') repoTreeBase = data.tree_base;
+    } catch (_) {
+      /* swallow — links degrade to the original relative href */
+    }
+  }
+
+  async function boot() {
+    const article = $('#primer-article');
+    if (!article) return;
+    let md;
+    try {
+      // Fetch markdown + repo bases in parallel. The bases must be populated
+      // BEFORE parseMarkdown runs so resolveLinkHref returns GitHub URLs
+      // (not the relative-href fallback).
+      const [mdRes] = await Promise.all([
+        fetch('/builders/primer.md', { credentials: 'same-origin' }),
+        loadRepoInfoBases(),
+      ]);
+      if (!mdRes.ok) throw new Error(`primer.md → ${mdRes.status}`);
+      md = await mdRes.text();
+    } catch (err) {
+      console.error('[primer] failed to load markdown', err);
+      article.innerHTML = `<p class="primer-loading">Could not load the primer. <a href="/builders">Go back</a> and try again.</p>`;
+      article.removeAttribute('aria-busy');
+      return;
+    }
+    const { html, headings } = parseMarkdown(md);
+    article.innerHTML = html;
+    article.removeAttribute('aria-busy');
+    inlineDiagrams(article);
+    const tocSections = renderToc(headings);
+    setupTocToggle();
+    setupScrollspy(tocSections);
+    setupProgressBar(article, onArticleProgress);
+    setupAck();
+    checkAlreadyAcked();
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', boot);
+  } else {
+    boot();
+  }
+})();