@bongos/core 1.19.473 → 1.19.475

package/docs/module-api-changelog.md

@@ -1383,5 +1383,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.471 with no explicit bump. run 33646171957. (task 1002620)
   1.19.473 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.472 with no explicit bump. run 33646919877. (task 1002620)
+  1.19.474 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.473 with no explicit bump. run 33650008858. (task 1002620)
+  1.19.475 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.474 with no explicit bump. run 33653632532. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -230,7 +230,7 @@
 
   // task 1723: which container a widget mounts into. A widget may declare
   // `zone` (a fine-grained Home slot), `group` (a Standing rail section, task
-  // 2174) or `view` (home/standing/leaderboard); all default to the Home main
+  // 2174) or `view` (home/standing); all default to the Home main
   // zone so pre-redesign module widgets still land somewhere visible. Every
   // container lives INSIDE <main>, so the `main .scroll` sweeps (newcomer gate,
   // landing hide-all) keep working.
@@ -910,26 +910,12 @@
     }
   }
 
-  // ---- leaderboard ---------------------------------------------------------
-
-  // Locked at 8 for V2 (per limitations/pms-v2.md). Hardcoding here avoids an
-  // extra API round-trip per page load — the catalog won't shift in V2.
-
-
-  // task 2174: OTBKit pager. 25/page is what task 1750 set for the top-100 Roll;
-  // the per-page select now lets a builder widen it and the choice persists.
-
-  // Stable sort. Server returns rows in drachmae-DESC order, which is also the
-  // default view; for other modes (rank, karma, drachmae-ASC), re-sort here.
-  // The original server order is preserved as a tie-breaker so equal-value rows
-  // don't jitter between renders. Drachmae is the secondary tie-breaker when
-  // sorting by karma (V3.R26 #246) so the karma toggle still reads sensibly
-  // when many builders share the same karma value (e.g. zero).
-
-  // Map a sortable column id → the lbState.sortBy key. Adding a new sortable
-  // column means adding an entry here + a header in hall-widgets.js with id
-  // `lb-sort-<key>`. The handler walks aria-sort across all sortable headers so
-  // only one column shows its arrow at a time.
+  // ---- the Roll’s rows, for the Standing card -----------------------------
+  //
+  // task 1003441 moved the leaderboard TABLE to its own page (/roster,
+  // roster.js): the pager, the sort lenses, LB_SORT_HEADERS and the achievement
+  // laurels went with it. Only the place lookup below stays — it needs the same
+  // rows, and the Standing card that shows it is on THIS page.
 
   // #757: this builder's place on the Roll, ranked by drachmae (total_credits)
   // descending — the canonical leaderboard order, independent of whatever column
@@ -939,28 +925,6 @@
   // builder isn't on the roll). Matched by github_login (rows carry no id).
 
 
-  // Cycle: pick column → desc → asc → back to default (drachmae desc).
-  // For a click on the active column we just flip direction; for a click on
-  // a different column we activate it at 'desc' (the natural "best first"
-  // direction for all three columns). Clicking the same column a third time
-  // returns to the default drachmae-desc — discoverable, no dead state.
-  function onLbSortClick(key) {
-    if (lbState.sortBy === key) {
-      if (lbState.sortDir === 'desc') {
-        lbState.sortDir = 'asc';
-      } else {
-        // Third click returns to the default view.
-        lbState.sortBy = 'drachmae';
-        lbState.sortDir = 'desc';
-      }
-    } else {
-      lbState.sortBy = key;
-      lbState.sortDir = 'desc';
-    }
-    lbPager.page = 1;
-    renderLeaderboard();
-  }
-
   // ---- onboarding live-tick poll (task 1444) -------------------------------
   //
   // The onboarding checklist is rendered once from the page-load /me snapshot.
@@ -1160,14 +1124,15 @@
 
     if (lb.status === 'fulfilled') {
       lbState.rows = lb.value.leaderboard || [];
-      lbPager.page = 1;
-      renderLeaderboard();
       // #757: the Standing card painted before the Roll loaded, so re-render it
       // now that lbState.rows exists — this is when its "#N on the Roll" stat
       // can resolve.
       if (lastMeState && lastMeState.builder) renderProfile(lastMeState.builder);
     } else {
-      $('#leaderboard tbody').innerHTML = emptyRow(5, 'The leaderboard could not be loaded.');
+      // The Roll’s rows only feed the Standing card’s "#N" stat now — the table
+      // itself is /roster (task 1003441) — so a failed fetch degrades that one
+      // stat rather than blanking a panel this page no longer has.
+      lbState.rows = [];
     }
   }
 
@@ -1241,25 +1206,9 @@
     // task 2174: the kit wires prev/next/per-page for both tables against the
     // #ships-*/#lb-* ids its own pagerBarHtml() stamped in hall-widgets.js.
     window.OTBKit.wirePager(shipsPager, renderRecentShips);
-    window.OTBKit.wirePager(lbPager, renderLeaderboard);
+
     window.OTBKit.wirePager(acclaimPager, renderAcclaimRows);
 
-    // Sortable leaderboard headers — clickable + keyboard-operable. Each
-    // sortable column registers under LB_SORT_HEADERS; the click handler
-    // routes the column key into the shared cycle.
-    for (const [key, headerId] of Object.entries(LB_SORT_HEADERS)) {
-      const head = document.getElementById(headerId);
-      if (!head) continue;
-      head.setAttribute('tabindex', '0');
-      head.setAttribute('role', 'button');
-      head.addEventListener('click', () => onLbSortClick(key));
-      head.addEventListener('keydown', (e) => {
-        if (e.key === 'Enter' || e.key === ' ') {
-          e.preventDefault();
-          onLbSortClick(key);
-        }
-      });
-    }
 
     // Sign-out is wired centrally in shell.js (doLogout + a delegated click
     // listener on the sign-out anchors), so it runs the real POST -> cookie-clear
@@ -1365,7 +1314,7 @@
   // reads what this page holds NOW rather than what it held at boot. Everything
   // else is stable for the life of the page. This call sits AFTER every
   // declaration it passes — moving it earlier is a temporal-dead-zone crash.
-  const { LB_SORT_HEADERS, SETUP_CONFIG_KEY, analyticsState, lbPager, lbState, mountHallWidgets, onboardingBox, renderCurveBody, renderLanding, renderLeaderboard, renderNav, renderOnboarding, renderProfile, renderRecentShips, renderWelcomeCore, shipState, shipsPager, welcomeDismissalKey } = window.OTBHallRender({
+  const { SETUP_CONFIG_KEY, analyticsState, lbState, mountHallWidgets, onboardingBox, renderCurveBody, renderLanding, renderNav, renderOnboarding, renderProfile, renderRecentShips, renderWelcomeCore, shipState, shipsPager, welcomeDismissalKey } = window.OTBHallRender({
     API, RANK_ORDER, api, brandWorld, curLabel, emptyRow, fmtDate, mins, normalizeRank, pct, postJSON, rankLabel, rankWeight, signClasses, toast, usd,
     get instanceRepo() { return instanceRepo; },
     get lastCostState() { return lastCostState; },

package/modules/hall-ui/public/dom-utils.js

@@ -153,7 +153,8 @@
   // third-party widget can't blank the hall (the structural id/label/mount
   // contract below still throws — that one is first-party programmer error).
   const HALL_ZONES = ['home-banner', 'home-stats', 'home-band', 'home-main'];
-  const HALL_VIEWS = ['home', 'standing', 'leaderboard'];
+  // task 1003441: 'leaderboard' left — it is a page (/roster) now, not a view.
+  const HALL_VIEWS = ['home', 'standing'];
 
   const _hallWidgets = [];
   function contributeHallWidget(widget) {

package/modules/hall-ui/public/drachmae.html

@@ -9,18 +9,17 @@
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
-  <!-- task 1003307: the reading-room archetype's own sheet. drachmae reuses the
-       primer's layout and loaded primer.css for it, but never room.css — so it
-       had the room's DOM and none of the room's world: no reading measure, no
-       prose-link 24px floor, no table wrapper. Loading it is the fix; the order
-       matches primer.html (room first, the page's own sheet on top). -->
+  <!-- The reading-room archetype is the whole of this page's sheet. primer.css
+       holds only the acknowledge gate, which a reference has no use for, so it
+       is no longer loaded here (task 1003473; it had been since task 1003307). -->
   <link rel="stylesheet" href="/builders/room.css">
-  <link rel="stylesheet" href="/builders/primer.css?v=2026-07-02-shell1">
 </head>
-<body class="room primer-body" data-page="drachmae" data-page-title="Drachmae &amp; karma">
-
-<!-- Reading-progress bar — fills as the reader scrolls through the article. -->
-<div class="primer-progress" aria-hidden="true"><div class="primer-progress__bar" id="primer-progress-bar"></div></div>
+<!-- `room` opts into the archetype's composition tokens (room.css); they sit on
+     the body, never in a page :root. `room--reference` is what the room owes a
+     document people SCAN rather than read (task 1003473): the outline goes to
+     h3 depth, every heading carries its own link, and the linear-read
+     instruments (the progress hairline, the section counters) are off. -->
+<body class="room room--reference" data-page="drachmae" data-page-title="Drachmae &amp; karma">
 
 <div class="app">
   <aside class="app-sidebar" id="app-sidebar" aria-label="Primary"></aside>
@@ -29,59 +28,66 @@
     <header class="app-topbar" id="app-topbar"></header>
     <div class="app-content">
 
-      <!-- task 1003307: the reading-room head. drachmae shares the primer's
-           .primer-layout and is read as a document, so it takes .page-head--room
-           (task 1003306's archetype) rather than the board's label voice — and
-           it gets the <h1> it never had. -->
+      <!-- The reading room announces its document (task 1003306's archetype):
+           the label voice on a one-word eyebrow, then the room's name lowercase
+           in the display face. The sub line says what KIND of document this is,
+           not how long it takes: nobody reads a reference to the end. -->
       <div class="page-head page-head--room">
         <p class="page-head__eyebrow">Docs</p>
         <h1 class="page-head__h">Drachmae &amp; karma</h1>
-        <p class="page-head__sub">How you get paid, and how you earn trust — the reward model in plain language. About a five-minute read.</p>
+        <p class="page-head__sub">How you get paid, and how you earn trust. A reference to jump around in: every section has its own link, and the bounty rates are read live.</p>
       </div>
 
       <main id="hall-main">
         <div class="primer-layout">
 
-          <!-- Sticky left-rail table of contents, built from the article's h2s. -->
-          <aside class="primer-toc" id="primer-toc" aria-label="Sections in this guide">
+          <!-- The outline. Built from the article's h2s AND h3s once the
+               markdown renders: a reference is found by its sub-questions, not
+               read in order, so the contents go a level deeper than the
+               primer's and carry no numerals. Under 760px it collapses behind a
+               toggle whose middle names the part the reader is in. -->
+          <aside class="primer-toc" id="primer-toc" aria-label="Sections in this reference">
             <button type="button" class="primer-toc__toggle" id="primer-toc-toggle" aria-expanded="false" aria-controls="primer-toc-list">
-              <span>Sections</span>
-              <span class="primer-toc__chevron" aria-hidden="true">▾</span>
+              <span class="primer-toc__toggle-label">On this page</span>
+              <span class="primer-toc__current" id="primer-toc-current"></span>
+              <svg class="primer-toc__chevron" viewBox="0 0 10 6" width="10" height="6" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M1 1.2 5 4.8 9 1.2"/></svg>
             </button>
             <nav class="primer-toc__inner">
-              <p class="primer-toc__heading" id="primer-toc-heading">In this guide</p>
+              <p class="primer-toc__heading" id="primer-toc-heading">On this page</p>
               <ol class="primer-toc__list" id="primer-toc-list" aria-labelledby="primer-toc-heading">
                 <li class="primer-toc__placeholder">Loading…</li>
               </ol>
             </nav>
           </aside>
 
-          <!-- Article column — markdown rendered here. -->
-          <!-- The room's loading shape: skeleton lines in the article's own
-               measure, not a sentence. (.primer-loading, which used to sit in the
-               article, is defined in no stylesheet and rendered unstyled.) -->
-          <div class="primer-skeleton scroll" id="primer-skeleton" aria-hidden="true">
-            <span class="primer-sk primer-skeleton__h"></span>
-            <div class="primer-skeleton__p">
-              <span class="primer-sk"></span>
-              <span class="primer-sk"></span>
-              <span class="primer-sk"></span>
-            </div>
-            <div class="primer-skeleton__rule"></div>
-            <div class="primer-skeleton__p">
-              <span class="primer-sk"></span>
-              <span class="primer-sk"></span>
+          <!-- The article column: three panels of the same card at the same
+               width (skeleton, document, failure), so the column never changes
+               shape as the markdown resolves. -->
+          <div class="primer-col">
+
+            <div class="primer-skeleton scroll" id="primer-skeleton" aria-hidden="true">
+              <span class="primer-sk primer-skeleton__h"></span>
+              <div class="primer-skeleton__p">
+                <span class="primer-sk"></span><span class="primer-sk"></span>
+                <span class="primer-sk"></span><span class="primer-sk"></span>
+                <span class="primer-sk"></span>
+              </div>
+              <div class="primer-skeleton__rule"></div>
+              <div class="primer-skeleton__p">
+                <span class="primer-sk"></span><span class="primer-sk"></span>
+                <span class="primer-sk"></span>
+              </div>
             </div>
-          </div>
 
-          <article class="primer-article scroll" id="primer-article" aria-busy="true" hidden></article>
+            <article class="primer-article scroll" id="primer-article" aria-busy="true" hidden></article>
 
-          <div class="primer-note primer-note--error scroll" id="primer-error" hidden>
-            <p class="primer-note__label">The guide did not load</p>
-            <p class="primer-note__body">The markdown behind this page could not be fetched. Reload to try again, or read it in the repo.</p>
-            <p class="primer-note__acts"><a class="btn btn--ghost" href="/builders">Back to home</a></p>
-          </div>
+            <div class="primer-note primer-note--error scroll" id="primer-error" hidden>
+              <p class="primer-note__label">The reference did not load</p>
+              <p class="primer-note__body">The markdown behind this page could not be fetched. Reload to try again, or read it in the repo.</p>
+              <p class="primer-note__acts"><a class="btn btn--ghost" href="/builders">Back to home</a></p>
+            </div>
 
+          </div>
         </div>
       </main>
 
@@ -95,8 +101,8 @@
 <script src="/builders/shell.js?v=2026-07-02-shell1"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
-<script src="/builders/md-reader.js?v=2026-07-05-mdreader-1"></script>
-<script src="/builders/drachmae.js?v=2026-07-05-drachmae-1" defer></script>
+<script src="/builders/md-reader.js?v=2026-09-02-mdreader-2"></script>
+<script src="/builders/drachmae.js?v=2026-09-02-drachmae-2" defer></script>
 <script src="/builders/copy-on-click.js?v=2026-06-01-copy-1" defer></script>
 </body>
 </html>

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

@@ -1,18 +1,28 @@
-// drachmae.js — the in-hall reader for the "Drachmae & karma" onboarding doc
-// (task 1472). Fetches the canonical markdown at /builders/drachmae-and-karma.md
-// (mounted from docs/onboarding/drachmae-and-karma.md — single source of truth,
-// also the one the primer links to) and renders it with the shared OTBMdReader,
-// so builders can read exactly how they get paid without leaving the hall for
-// GitHub. Reuses the primer's layout/TOC/progress DOM + primer.css; no ack gate
-// (this is reference reading, not an onboarding checkpoint).
+// drachmae.js — the in-hall reader for the "Drachmae & karma" doc (task 1472),
+// rebuilt as the hall's first REFERENCE room (task 1003473, goal 1000081).
+// Fetches the canonical markdown at /builders/drachmae-and-karma.md (mounted
+// from docs/onboarding/drachmae-and-karma.md — single source of truth, also the
+// one the primer links to) and renders it through the shared OTBMdReader, so
+// builders can read exactly how they get paid without leaving the hall.
 //
-// task 2174: the red-team bounty rate card moved here off Standing. It is a
-// published reward SCHEDULE — reference material that reads the same for every
-// builder — so it belongs with the rest of the reward model, not in a personal
-// standing view. The doc's §"Red-team / security bounty" describes it in prose;
-// the LIVE numbers come from /public/bounty-table and are appended as a real
-// section (h2 + table) so the TOC, scrollspy and progress bar pick it up like
-// any other section of the article.
+// WHAT A REFERENCE OWES THAT THE PRIMER DOES NOT. People arrive at this page to
+// answer one question about how they get paid, so it is scanned and deep-linked
+// rather than read start to finish. Three things follow, and they are the whole
+// difference between this file and primer.js (the room itself — the layout, the
+// glass contents, the card — is room.css's, shared):
+//   * the outline goes to h3 depth and the scrollspy lights the section AND
+//     its part (the trail), with the phone toggle naming where the reader is;
+//   * every h2/h3/h4 carries its own link (.room-anchor), which copies the
+//     address on click, and a deep link lands after the async render;
+//   * there is no progress hairline and no acknowledge gate: a reference has
+//     no end to reach.
+//
+// task 2174: the red-team bounty rate card lives here. It is a published reward
+// SCHEDULE — reference material that reads the same for every builder — so it
+// belongs with the rest of the reward model. The doc's §"Red-team / security
+// bounty" describes it in prose; the LIVE numbers come from /public/bounty-table
+// and are inserted as a real section (h2 + table) ahead of the closing links,
+// so the outline and the scrollspy pick it up like any other section.
 
 (() => {
   'use strict';
@@ -23,12 +33,31 @@
   const BOUNTY_URL = '/api/gds/public/bounty-table';
   const BOUNTY_SECTION_ID = 'security-bounty-rates';
   const BOUNTY_SECTION_TITLE = 'Security bounty rates';
+  // The section the live table is inserted AHEAD of: the doc's closing links.
+  // Matched by its opening words, so a retitled footer falls back to appending.
+  const CLOSING_H2 = /^see it/i;
+  // The y (viewport space) treated as "where the reader is looking": below the
+  // sticky top bar, where the eye lands reading down a page.
+  const READING_LINE_Y = 100;
+  const LINK_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6.6 9.4a2.7 2.7 0 0 0 3.8 0l2.3-2.3a2.7 2.7 0 0 0-3.8-3.8L7.7 4.5"/><path d="M9.4 6.6a2.7 2.7 0 0 0-3.8 0L3.3 8.9a2.7 2.7 0 0 0 3.8 3.8l1.2-1.2"/></svg>';
 
   let repoBlobBase = null;
   let repoTreeBase = null;
 
   function $(sel) { return document.querySelector(sel); }
 
+  // The shell's toast (style.css .toast[data-visible="1"]), the same contract
+  // primer.js and copy-on-click.js speak; this page loads no dom-utils.js.
+  function toast(msg) {
+    const el = $('#toast');
+    if (!el) return;
+    el.textContent = msg;
+    el.dataset.type = 'info';
+    el.dataset.visible = '1';
+    clearTimeout(toast._t);
+    toast._t = setTimeout(() => { el.dataset.visible = '0'; }, 2400);
+  }
+
   async function loadRepoInfoBases() {
     try {
       const r = await fetch('/api/gds/public/repo-info', { credentials: 'same-origin' });
@@ -39,10 +68,11 @@
     } catch (_) { /* links degrade to the original href */ }
   }
 
-  // Append the live bounty rate card to the article and return its TOC heading,
-  // or null when the schedule can't be read (the prose section stays; we just
-  // don't show an empty table or a TOC entry that leads nowhere).
-  async function appendBountySection(article) {
+  // The live rate card as a real section of the article, placed ahead of the
+  // closing links so the doc still ends on "dig deeper". Returns false when the
+  // schedule can't be read: the prose section stays, and no empty table or
+  // outline entry that leads nowhere is rendered.
+  async function insertBountySection(article) {
     let payload;
     try {
       const r = await fetch(BOUNTY_URL, { credentials: 'same-origin' });
@@ -50,19 +80,19 @@
       payload = await r.json();
     } catch (err) {
       console.warn('[drachmae] bounty schedule unavailable:', err.message);
-      return null;
+      return false;
     }
     const rows = Array.isArray(payload && payload.table) ? payload.table : [];
-    if (!rows.length) return null;
+    if (!rows.length) return false;
 
     const esc = window.OTBMdReader.escapeHtml;
     const currency = payload.currency || 'credits';
     const section = document.createElement('section');
     section.innerHTML =
       `<h2 id="${esc(BOUNTY_SECTION_ID)}">${esc(BOUNTY_SECTION_TITLE)}</h2>` +
-      `<p>Find a flaw in the system’s own walls and report it — rewards are paid in ` +
+      `<p>Find a flaw in the system’s own walls and report it: rewards are paid in ` +
       `${esc(currency)} by severity. These are the live numbers, read from the server ` +
-      `just now, so a tuned rate shows up here immediately.</p>` +
+      `when you opened this page, so a tuned rate shows up here immediately.</p>` +
       '<table><thead><tr><th>Severity</th>' +
       `<th>${esc(currency.charAt(0).toUpperCase() + currency.slice(1))}</th>` +
       '<th>What counts</th></tr></thead><tbody>' +
@@ -74,58 +104,117 @@
           `<td>${esc(r.blurb || '')}</td></tr>`;
       }).join('') +
       '</tbody></table>';
-    article.appendChild(section);
-    return { level: 2, id: BOUNTY_SECTION_ID, text: BOUNTY_SECTION_TITLE };
+    const closing = [...article.querySelectorAll('h2')].find((h) => CLOSING_H2.test(h.textContent.trim()));
+    if (closing) article.insertBefore(section, closing); else article.appendChild(section);
+    return true;
+  }
+
+  // The outline is read from the RENDERED headings rather than the parser's raw
+  // text, so `*not*` and a [link](…) in a heading arrive as plain words, and so
+  // the live section inserted above is simply one more heading in order.
+  function collectHeadings(article) {
+    return [...article.querySelectorAll('h2[id], h3[id]')].map((el) => ({
+      level: Number(el.tagName.charAt(1)), id: el.id, text: el.textContent.trim(),
+    }));
   }
 
+  // h2s as the list, each h3 nested under its part; no numerals (room.css turns
+  // the room's counter off for a reference). Returns the flat list in document
+  // order, each entry carrying its part's id and title, which is what the
+  // scrollspy walks and what the phone toggle names.
   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 []; }
+    if (headings.length === 0) { list.innerHTML = '<li class="primer-toc__placeholder">(no sections)</li>'; return []; }
     const esc = window.OTBMdReader.escapeHtml;
-    list.innerHTML = h2s.map((h) =>
-      `<li><a href="#${esc(h.id)}" data-section="${esc(h.id)}">${esc(h.text)}</a></li>`
+    const link = (h) => `<a href="#${esc(h.id)}" data-section="${esc(h.id)}">${esc(h.text)}</a>`;
+    const parts = [];
+    for (const h of headings) {
+      const last = parts[parts.length - 1];
+      if (h.level === 3 && last) last.subs.push(h);
+      else parts.push({ head: h, subs: [] });
+    }
+    list.innerHTML = parts.map((p) =>
+      `<li>${link(p.head)}${p.subs.length
+        ? `<ol class="primer-toc__sub">${p.subs.map((s) => `<li>${link(s)}</li>`).join('')}</ol>`
+        : ''}</li>`
     ).join('');
-    return h2s;
+    const flat = [];
+    for (const p of parts) {
+      flat.push({ id: p.head.id, parent: null, part: p.head.text });
+      for (const s of p.subs) flat.push({ id: s.id, parent: p.head.id, part: p.head.text });
+    }
+    return flat;
   }
 
-  function setupScrollspy(tocSections) {
-    if (tocSections.length === 0) return;
+  // The active entry is the LAST heading whose top has scrolled past the
+  // reading line, so it stays put through a section's paragraphs. Its part, when
+  // the active entry is an h3, is the trail; the toggle's middle names the part.
+  function setupScrollspy(sections) {
+    if (sections.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;
-    const READING_LINE_Y = 100;
+    const current = $('#primer-toc-current');
     let last = null;
     function update() {
       let active = null;
-      for (const s of tocSections) {
+      for (const s of sections) {
         const el = document.getElementById(s.id);
         if (!el) continue;
-        if (el.getBoundingClientRect().top <= READING_LINE_Y) active = s.id; else break;
+        if (el.getBoundingClientRect().top <= READING_LINE_Y) active = s; else break;
+      }
+      const id = active ? active.id : null;
+      if (id === last) return;
+      last = id;
+      const trail = active && active.parent;
+      for (const [sid, a] of links) {
+        a.classList.toggle('is-active', sid === id);
+        a.classList.toggle('is-trail', !!trail && sid === trail);
       }
-      if (active === last) return;
-      last = active;
-      for (const [id, a] of links) a.classList.toggle('is-active', id === active);
+      if (current) current.textContent = active ? active.part : '';
     }
     window.addEventListener('scroll', update, { passive: true });
     window.addEventListener('resize', update, { passive: true });
     update();
   }
 
-  function setupProgressBar(articleEl) {
-    const bar = $('#primer-progress-bar');
-    if (!bar) return;
-    function update() {
-      const rect = articleEl.getBoundingClientRect();
-      const viewport = window.innerHeight || document.documentElement.clientHeight;
-      const scrolled = Math.max(0, -rect.top);
-      const frac = rect.height > 0 ? Math.min(1, scrolled / Math.max(1, rect.height - viewport)) : 0;
-      bar.style.width = `${Math.round(frac * 100)}%`;
+  // Every heading is an address. The link is the heading's own id, so it works
+  // with the browser's hash navigation and no script; the click additionally
+  // copies the absolute address, so a reader can hand a colleague the exact
+  // answer, which is the reason a reference is deep-linked at all.
+  function addAnchors(article) {
+    for (const h of article.querySelectorAll('h2[id], h3[id], h4[id]')) {
+      const a = document.createElement('a');
+      a.className = 'room-anchor';
+      a.href = `#${h.id}`;
+      a.setAttribute('aria-label', `Link to this section: ${h.textContent.trim()}`);
+      a.innerHTML = LINK_ICON;
+      h.appendChild(a);
     }
-    window.addEventListener('scroll', update, { passive: true });
-    window.addEventListener('resize', update, { passive: true });
-    update();
+    article.addEventListener('click', (e) => {
+      const a = e.target.closest('a.room-anchor');
+      if (!a) return;
+      if (!(navigator.clipboard && navigator.clipboard.writeText && window.isSecureContext)) return;
+      const url = new URL(a.getAttribute('href'), window.location.href).href;
+      navigator.clipboard.writeText(url).then(() => toast('Link copied.'), () => { /* the hash still navigated */ });
+    });
+  }
+
+  // A deep link arrives before the article exists, so the browser's own jump
+  // finds nothing and its :target was resolved against nothing. Once the
+  // document and the live section are in the DOM the target is scrolled into
+  // view (scroll-margin-top clears the top bar) and marked (.is-target) until
+  // the next hash change hands the mark back to :target.
+  function landOnHash() {
+    let id = '';
+    // a malformed percent-escape in the fragment throws; there is nothing to land on
+    try { id = decodeURIComponent(window.location.hash.slice(1)); } catch (_) { return; }
+    const el = id && document.getElementById(id);
+    if (!el) return;
+    el.classList.add('is-target');
+    el.scrollIntoView({ block: 'start' });
+    window.addEventListener('hashchange', () => el.classList.remove('is-target'), { once: true });
   }
 
   function setupTocToggle() {
@@ -146,8 +235,7 @@
     });
   }
 
-  // The three panels the article can resolve into (the primer's show(), which
-  // this page's DOM has mirrored since task 1472 and now finally matches).
+  // The three panels the article can resolve into (the primer's show()).
   function show(which) {
     for (const [id, on] of [['#primer-skeleton', which === 'loading'],
                             ['#primer-article', which === 'article'],
@@ -185,18 +273,18 @@
     // The doc's leading "# …" is the same page name .page-head--room already
     // renders. Two <h1>s fails one-header-main-h1, and the page head is the one
     // that exists before the fetch and survives its failure (task 1003307).
-    const html = parsed.html.replace(/^\s*<h1\b[^>]*>[\s\S]*?<\/h1>\s*/, '');
-    const headings = parsed.headings.filter((h) => h.level > 1);
-    article.innerHTML = html;
+    article.innerHTML = parsed.html.replace(/^\s*<h1\b[^>]*>[\s\S]*?<\/h1>\s*/, '');
     article.removeAttribute('aria-busy');
     show('article');
-    // Awaited before the TOC is built so the rate card gets a TOC entry and a
+    // Awaited before the outline is built so the rate card gets its entry and a
     // scrollspy target; the article itself is already on screen by now.
-    const bountyHeading = await appendBountySection(article);
-    const tocSections = renderToc(bountyHeading ? [...headings, bountyHeading] : headings);
+    await insertBountySection(article);
+    addAnchors(article);
     setupTocToggle();
-    setupScrollspy(tocSections);
-    setupProgressBar(article);
+    setupScrollspy(renderToc(collectHeadings(article)));
+    // After the fonts: a swap after the jump moves everything above the target
+    // (measured: 300px short on a phone, past it on a desktop).
+    (document.fonts ? document.fonts.ready : Promise.resolve()).then(landOnHash);
   }
 
   if (document.readyState === 'loading') {