@bongos/core 1.19.448 → 1.19.450

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

@@ -1,36 +1,39 @@
 // 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).
+// renders it through the SHARED reader (md-reader.js / window.OTBMdReader),
+// inlines the five onboarding diagrams at matching sections, builds a TOC from
+// h2s with a scrollspy, drives a reading-progress hairline, 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.
+// ONE PARSER, TWO READERS (task 1003306). This file used to carry its own copy
+// of the markdown parser — the same grammar as md-reader.js minus blockquotes,
+// which meant every `> aside` in the primer silently collapsed into a
+// paragraph. md-reader.js was always the fuller of the two, so the copy is gone
+// and the difference that is genuinely the primer's — the diagram injected
+// after a named h2 — is all that is left here. Anything the primer's markdown
+// needs that the grammar lacks belongs in md-reader.js, where the economy
+// reader gets it too.
 
 (() => {
   '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.
+  // The primer markdown lives at docs/onboarding/primer.md, so its relative
+  // links resolve against docs/onboarding/.
+  const PRIMER_DIR = 'docs/onboarding/';
+  // 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. They are fetched
+  // from /api/gds/public/repo-info at boot; the server derives owner/repo at
+  // process start from `git remote get-url origin` (src/bongos/repo-info.js).
+  // When they are unavailable the rewriter degrades gracefully: repo-relative
+  // hrefs pass through unchanged and 404 instead of crashing the page.
   let repoBlobBase = null;
   let repoTreeBase = null;
 
@@ -52,27 +55,21 @@
 
   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, '-');
-  }
+  const MD = window.OTBMdReader;
+  const escapeHtml = (MD && MD.escapeHtml) || ((s) => String(s));
+
+  // The shared resolver, plus the one rewrite that is the primer's alone: the
+  // economy doc has an in-hall reader page (task 1472), so a link to it stays in
+  // the hall instead of bouncing the reader out to GitHub.
+  const resolveLinkHref = (() => {
+    if (!MD) return (h) => h;
+    const base = MD.makeResolveLinkHref({
+      baseDir: PRIMER_DIR,
+      getBlobBase: () => repoBlobBase,
+      getTreeBase: () => repoTreeBase,
+    });
+    return (href) => (href === 'drachmae-and-karma.md' ? '/builders/drachmae' : base(href));
+  })();
 
   function toast(msg, type) {
     // Shared toast mechanism (style.css .toast[data-visible="1"]) — same
@@ -86,253 +83,11 @@
     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.
+  // This is the ONLY parser-adjacent work that is the primer's own; everything
+  // above it is md-reader.js's.
   // -----------------------------------------------------------------------
 
   function inlineDiagrams(articleEl) {
@@ -364,7 +119,8 @@
   }
 
   // -----------------------------------------------------------------------
-  // TOC — built from h2 headings.
+  // TOC — built from h2 headings. The numeral is drawn by room.css's counter,
+  // so the markup carries only the title.
   // -----------------------------------------------------------------------
 
   function renderToc(headings) {
@@ -372,7 +128,7 @@
     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>';
+      list.innerHTML = '<li class="primer-toc__placeholder">No sections yet</li>';
       return [];
     }
     list.innerHTML = h2s.map((h) =>
@@ -428,7 +184,7 @@
   }
 
   // -----------------------------------------------------------------------
-  // Reading-progress bar — fraction of the article scrolled past.
+  // Reading-progress hairline — fraction of the article scrolled past.
   // -----------------------------------------------------------------------
 
   function setupProgressBar(articleEl, onProgress) {
@@ -437,13 +193,8 @@
     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;
+      const frac = rect.height > 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);
     }
@@ -454,18 +205,30 @@
 
   // -----------------------------------------------------------------------
   // Footer ack module — soft gate on the 'I have read it' button.
+  //
+  // The gate is aria-disabled, NOT disabled (task 1003306). A real `disabled`
+  // button leaves the tab order entirely, so a keyboard reader can never land
+  // on it and never hears the note saying WHY it is locked. aria-disabled keeps
+  // it reachable and describable; the handler below is what actually refuses
+  // the press.
   // -----------------------------------------------------------------------
 
   let ackEnabled = false;
+  function setLocked(btn, locked) {
+    btn.setAttribute('aria-disabled', locked ? 'true' : 'false');
+  }
+  function isLocked(btn) {
+    return btn.getAttribute('aria-disabled') !== '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;
+      if (!ackEnabled || isLocked(btn)) return;
+      setLocked(btn, true);
       btn.textContent = 'Marking…';
       try {
         const resp = await fetch(`${API}/builders/me/onboarding/primer-read`, {
@@ -492,7 +255,7 @@
         toast('Primer acknowledged.', 'success');
       } catch (err) {
         console.error('[primer] ack failed', err);
-        btn.disabled = false;
+        setLocked(btn, false);
         btn.textContent = 'I have read it';
         toast('Could not mark the primer just now. Try again.', 'error');
       }
@@ -506,11 +269,15 @@
   function showAckedState(message) {
     const btn = $('#primer-ack-btn');
     const lede = $('#primer-ack-lede');
+    const meter = $('#primer-ack-meter');
+    const locked = $('#primer-ack-note-locked');
     const note = $('#primer-ack-note');
-    const inner = document.querySelector('.primer-ack__inner');
+    const section = $('#primer-ack');
     if (btn) btn.hidden = true;
     if (lede) lede.hidden = true;
-    if (inner) inner.classList.add('primer-ack__inner--acked');
+    if (meter) meter.hidden = true;
+    if (locked) locked.hidden = true;
+    if (section) section.classList.add('primer-ack--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>.`;
@@ -518,12 +285,26 @@
   }
 
   function onArticleProgress(frac) {
+    const btn = $('#primer-ack-btn');
+    const meter = $('#primer-ack-meter');
+    // The meter reads the reader's own progress against the gate, so "locked"
+    // is a measurement they can watch move rather than a refusal.
+    if (meter && !ackEnabled && !(btn && btn.dataset.alreadyAcked)) {
+      const pct = Math.min(99, Math.round(frac * 100));
+      const need = Math.round(ACK_SCROLL_THRESHOLD * 100);
+      meter.innerHTML = `Read <span class="primer-ack__num">${pct}%</span> of the ${need}% needed`;
+    }
     if (frac >= ACK_SCROLL_THRESHOLD && !ackEnabled) {
-      const btn = $('#primer-ack-btn');
       const lede = $('#primer-ack-lede');
+      const locked = $('#primer-ack-note-locked');
       if (btn && !btn.dataset.alreadyAcked) {
-        btn.disabled = false;
+        setLocked(btn, false);
+        // the note explained the lock; with the lock gone it would describe a
+        // control that is no longer locked, so it goes with it
+        btn.removeAttribute('aria-describedby');
         ackEnabled = true;
+        if (meter) meter.hidden = true;
+        if (locked) locked.hidden = true;
       }
       if (lede) {
         lede.textContent = 'You have reached the end. The button below is now active.';
@@ -601,9 +382,27 @@
     }
   }
 
+  // The three panels the article can resolve into. Each is the same card at the
+  // same width, so the column never changes shape as the document arrives.
+  function show(which) {
+    for (const [id, on] of [['#primer-skeleton', which === 'loading'],
+                            ['#primer-article', which === 'article'],
+                            ['#primer-error', which === 'error']]) {
+      const el = $(id);
+      if (el) el.hidden = !on;
+    }
+  }
+
   async function boot() {
     const article = $('#primer-article');
     if (!article) return;
+    if (!MD) {
+      // md-reader.js is loaded before this file; without it there is no parser
+      // at all, so say so rather than rendering an empty room.
+      console.error('[primer] md-reader.js did not load — no parser available');
+      show('error');
+      return;
+    }
     let md;
     try {
       // Fetch markdown + repo bases in parallel. The bases must be populated
@@ -617,13 +416,13 @@
       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');
+      show('error');
       return;
     }
-    const { html, headings } = parseMarkdown(md);
+    const { html, headings } = MD.parseMarkdown(md, resolveLinkHref);
     article.innerHTML = html;
     article.removeAttribute('aria-busy');
+    show('article');
     inlineDiagrams(article);
     const tocSections = renderToc(headings);
     setupTocToggle();

package/modules/hall-ui/public/primer.states.json

@@ -0,0 +1,38 @@
+{
+  "_": "The hall's primer through modules/ui-design/kit/render.js (task 1003306). Written with the reading-room re-skin so the room's failure state and its table of contents are MEASURED at 1440/390/320 in both modes, not just looked at.",
+  "page": "/builders/primer",
+  "surface": "hall-ui",
+  "stub": { "prefix": "/builders/" },
+  "modeQuery": false,
+  "_feeds": "The kit's stub carries the public-landing fixtures, not the hall's, and it serves no /builders/primer.md at all — so the room renders its SKELETON and then its FAILURE note here, which is the point: the two states before the document are the ones nobody looks at, and they have to hold the floors too. The populated document is the hall-preview harness's job: node scripts/hall-preview/server.js --port 4612 --fixture-me, then this same file with --base-in/--base-out pointed at it.",
+  "ignoreRequests": [
+    "/api/(gds|bongos)/me$",
+    "/api/(gds|bongos)/me/",
+    "/api/(gds|bongos)/goals",
+    "/api/(gds|bongos)/inbox/",
+    "/api/(gds|bongos)/public/repo-info",
+    "/builders/primer.md"
+  ],
+  "ignoreConsole": [
+    "/api/(gds|bongos)/",
+    "\\b401\\b",
+    "\\b404\\b",
+    "Unauthorized",
+    "Not Found",
+    "primer.md",
+    "failed to load markdown",
+    "load failed"
+  ],
+  "_expect": "The expectations name only what is true under BOTH bases. Under the kit stub there is no primer.md, so the failure note renders; under the harness the real document does. Pinning either one would make this file pass in one place and fail in the other, which is how a states file stops being run against the harness at all.",
+  "states": {
+    "in": { "auth": true, "expect": { "visible": ["#hall-main", "#primer-toc"] } },
+    "toc-open": {
+      "auth": true,
+      "actions": [["clickIfVisible", "#primer-toc-toggle"], ["wait", 250]],
+      "_": "the room's one disclosure. Below 760px the contents collapse behind this toggle; above it the toggle is not rendered at all, so clickIfVisible is the right verb and the state is a no-op at 1440.",
+      "expect": { "visible": ["#primer-toc"] }
+    },
+    "out": { "auth": false }
+  },
+  "reducedMotion": { "auth": true }
+}

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

@@ -18,7 +18,15 @@
   <div class="app-body">
     <header class="app-topbar" id="app-topbar"></header>
     <div class="app-content">
-      <div class="page-head">
+      <!-- The page had no <h1> at all before task 1003306, so it failed
+           one-header-main-h1 on every render — the finding ranks.states.json
+           has been carrying in the open since task 1003320. Ranks is a reading
+           room by archetype (docs/design/hall-direction-v2.md §1), so it takes
+           the room's head: the label voice on the eyebrow, the room's name in
+           the display face. -->
+      <div class="page-head page-head--room">
+        <p class="page-head__eyebrow">Docs</p>
+        <h1 class="page-head__h">Ranks</h1>
         <p class="page-head__sub" id="ranks-sub">Loading your rank…</p>
       </div>
 

package/modules/hall-ui/public/ranks.states.json

@@ -4,7 +4,7 @@
   "surface": "hall-ui",
   "stub": { "prefix": "/builders/" },
   "modeQuery": false,
-  "_feeds": "The hall's shell polls goals + inbox + profile feeds on every page; the stub fixtures only the public feeds, so those 404s are declared here, not hidden by the kit. The 24px-floor and h1 findings the render reports are REAL (the hall predates the floor) and are deliberately not ignored.",
+  "_feeds": "The hall's shell polls goals + inbox + profile feeds on every page; the stub fixtures only the public feeds, so those 404s are declared here, not hidden by the kit. (The 24px-floor and h1 findings this file used to carry in the open are FIXED, not silenced: the badge grew to 24px in task 1003304, and the page got its <h1> with the reading-room re-skin in task 1003306. The render is clean; nothing here ignores a floor.)",
   "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox/", "/api/(gds|bongos)/me/"],
   "ignoreConsole": ["/api/(gds|bongos)/me", "\\b401\\b", "Unauthorized", "404 \\(Not Found\\)", "goals load failed"],
   "states": {