@bongos/core 1.19.448 → 1.19.450

package/tests/hall_reading_world.mjs

@@ -0,0 +1,430 @@
+// tests/hall_reading_world.mjs — the READING ROOMS in the chrome world: the
+// primer, the diagrams index, the roadmap deck and the ranks ladder
+// (task 1003306, goal 1000081).
+//
+// tests/hall_tokens.mjs pins the TIER these pages spend, hall_board_world.mjs
+// pins how the board spends it and hall_record_world.mjs the record family;
+// this is the same job for the reading rooms. Everything here is a fact that is
+// SILENT in a browser: the page still renders, it just renders wrong, or it
+// renders right here and fails a floor on the reviewer's machine.
+//
+// What it locks:
+//   * THE PAGE-LOCAL `:root` STAYS GONE. roadmap.css declared one — the only
+//     one in the hall, and forbidden both ways: the branding pack's :root is
+//     spliced at the END of <head> at (0,1,0), so a page-local one is outranked
+//     one way and defeats re-branding the other. Page tokens live on `body`.
+//   * ONE MARKDOWN PARSER. primer.js carried its own copy of md-reader.js's
+//     grammar minus blockquotes, so every `> aside` in the primer silently
+//     collapsed into a paragraph. The copy is gone; the pin is that it stays
+//     gone AND that the room has a blockquote rule to render what now arrives.
+//   * THE SOFT GATE IS aria-disabled. A real `disabled` button leaves the tab
+//     order, so a keyboard reader can never land on the acknowledge control and
+//     never hears the note saying why it is locked.
+//   * THE `ch` TRAP. primer.css capped the article at `72ch` under a comment
+//     claiming 60-72 characters; a `ch` is the font's ZERO glyph and Manrope's
+//     is wide, so it rendered about 90. The measure is --measure, and it is
+//     spent on PROSE only — on a display heading it is the inverse mistake
+//     hall_record_world §8 pins.
+//   * THE DRIFT FALLBACKS. diagram-viewer.css carried eleven
+//     `var(--x, LITERAL)` pairs whose tokens all exist, so the literal never
+//     rendered and only encoded drift (its --ink fallback said #2a2a2a where
+//     the sheet ships #17181a). Plus two raw shadows and a hand-written
+//     z-index: 9999.
+//   * THE SCROLL LOCK IS ON THE ROOT. The diagram's fullscreen locked `body`
+//     where the shell's own drawer locks `html`. Two overlays locking one page
+//     on two different elements is how one of them stops working.
+//   * THE ONE h1, ON EVERY ROOM. All four pages had none — the finding
+//     ranks.states.json had been carrying in the open since task 1003320.
+//   * THE COMPAT ALIASES. Each re-skinned sheet's removal list. The aliases
+//     still EXIST for the pages nobody has re-skinned, so spending one here is
+//     legal CSS that quietly opts the sheet back out of the world.
+//
+// Reproduce the renders these came from. The floors run against the kit's own
+// stub; the POPULATED document needs the fixture harness, because neither the
+// primer markdown nor the generated diagrams are the kit stub's to serve:
+//   node modules/ui-design/kit/render.js --states modules/hall-ui/public/primer.states.json
+//   node scripts/hall-preview/server.js --port 4612 --fixture-me
+//   node modules/ui-design/kit/render.js --states modules/hall-ui/public/primer.states.json \
+//     --base-in http://builders.localhost:4612 --base-out http://builders.localhost:4612
+//   (likewise diagrams.states.json, roadmap.states.json, ranks.states.json)
+//
+// §10 leaves static analysis behind and RUNS md-reader.js in a vm: the parser
+// unification is a behaviour claim, and "primer.js no longer contains a
+// parser" only proves half of it. The other half is that the parser it now
+// calls emits what the primer's markdown needs.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const styleCss = read('style.css');
+const roomCss = read('room.css');
+const primerCss = read('primer.css');
+const diagramsCss = read('diagrams.css');
+const roadmapCss = read('roadmap.css');
+const viewerCss = read('diagram-viewer.css');
+const primerJs = read('primer.js');
+const viewerJs = read('diagram-viewer.js');
+const mdReaderJs = read('md-reader.js');
+const primerHtml = read('primer.html');
+const diagramsHtml = read('diagrams.html');
+const roadmapHtml = read('roadmap.html');
+const ranksHtml = read('ranks.html');
+
+const decomment = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+// The body of the first rule matching `selector {`, comments stripped. Naive on
+// purpose: these are flat declaration blocks, not nested at-rules. Takes a PLAIN
+// selector and escapes it here — pass a pre-escaped one and it is escaped twice.
+const rule = (css, selector) => {
+  const esc = selector.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = decomment(css).match(new RegExp(`(^|[},])\\s*${esc}\\s*\\{([^}]*)\\}`, 'm'));
+  return m ? m[2] : null;
+};
+
+// The sheets this task re-skinned. A sheet joins this list when its page family
+// lands, and never leaves it.
+const RESKINNED = [
+  ['room.css', roomCss],
+  ['primer.css', primerCss],
+  ['diagrams.css', diagramsCss],
+  ['roadmap.css', roadmapCss],
+  ['diagram-viewer.css', viewerCss],
+];
+
+// ---- 1. no page declares its own :root -------------------------------------
+
+test('no hall page sheet declares a :root of its own', () => {
+  const offenders = [];
+  for (const f of fs.readdirSync(HALL).filter((n) => n.endsWith('.css') && n !== 'style.css')) {
+    if (/(^|[},])\s*:root\s*\{/.test(decomment(read(f)))) offenders.push(f);
+  }
+  assert.deepEqual(offenders, [],
+    'the pack :root is spliced at the end of <head> — a page-local one is outranked one way and defeats re-branding the other. Put page tokens on body.');
+});
+
+test('roadmap.css puts its three helpers on the body, scoped to the page', () => {
+  const body = rule(roadmapCss, 'body[data-page="roadmap"]');
+  assert.ok(body, 'roadmap.css declares its tokens on body[data-page="roadmap"]');
+  for (const t of ['--rm-plan', '--rm-terra-weak']) {
+    assert.match(body, new RegExp(`${t}\\s*:`), `${t} survived the move to body`);
+  }
+  assert.doesNotMatch(decomment(roadmapCss), /--rm-shadow-soft/,
+    'v3 separates by TONE — a panel is never a drawn box and never a shadow');
+  assert.doesNotMatch(decomment(roadmapCss), /box-shadow\s*:\s*(?!inset)[^;]*(?:rgba|0 )/,
+    'no raw shadow came back with it');
+});
+
+test('the :root guard CATCHES a reintroduction and tolerates a lookalike', () => {
+  assert.match(decomment(':root { --x: 1px; }'), /(^|[},])\s*:root\s*\{/);
+  assert.doesNotMatch('html:root-ish { }', /(^|[},])\s*:root\s*\{/);
+});
+
+// ---- 2. the compat aliases are retired from the re-skinned sheets ----------
+
+const ALIASES = ['--surface', '--surface-2', '--border', '--border-strong', '--accent-weak', '--accent-text'];
+
+test('no re-skinned reading-room sheet spends a compat alias', () => {
+  const found = [];
+  for (const [name, css] of RESKINNED) {
+    for (const alias of ALIASES) {
+      // \b would match --surface inside --surface-2, so require the var() close
+      if (new RegExp(`var\\(\\s*${alias}\\s*[,)]`).test(decomment(css))) found.push(`${name}: ${alias}`);
+    }
+  }
+  assert.deepEqual(found, [],
+    'the aliases exist for pages nobody has re-skinned; spending one here quietly opts the sheet back out of the world');
+});
+
+test('the ranks page section of style.css spends the real names too', () => {
+  const card = rule(styleCss, '.rank-card');
+  assert.ok(card, '.rank-card has a rule');
+  for (const alias of ALIASES) {
+    assert.doesNotMatch(card, new RegExp(`var\\(\\s*${alias}\\s*[,)]`), `.rank-card no longer spends ${alias}`);
+  }
+  assert.match(card, /border:\s*var\(--line\)\s+solid\s+transparent/,
+    'the edge is reserved as transparent so a modifier can draw one — collab.css\'s .btn--quiet is the precedent');
+});
+
+test('the alias guard would CATCH --surface without matching --surface-2', () => {
+  const re = new RegExp('var\\(\\s*--surface\\s*[,)]');
+  assert.ok(re.test('background: var(--surface);'));
+  assert.ok(!re.test('background: var(--surface-2);'));
+});
+
+// ---- 3. --measure is the BODY measure, and nothing else --------------------
+
+test('the room measures PROSE, and lets a table, a figure and a code block run wider', () => {
+  const measured = decomment(roomCss).match(/\.primer-article\s*>\s*p,[\s\S]*?\{([^}]*)\}/);
+  assert.ok(measured, 'room.css caps the prose children explicitly, not the card');
+  assert.match(measured[1], /max-width:\s*var\(--measure\)/);
+  const article = rule(roomCss, '.primer-article');
+  assert.ok(article, '.primer-article has a rule');
+  assert.doesNotMatch(article, /max-width/,
+    'the CARD is not capped at the measure — a table and a diagram may take its whole width');
+});
+
+test('no reading sheet does fresh `ch` arithmetic in prose', () => {
+  for (const [name, css] of RESKINNED) {
+    // A `ch` is the ZERO glyph's width, not a character: primer.css's 72ch
+    // rendered ~90. --measure was measured; a fresh number is a guess.
+    const hits = [...decomment(css).matchAll(/max-width:\s*(\d+(?:\.\d+)?)ch/g)].map((m) => m[0]);
+    assert.deepEqual(hits, [], `${name} caps a measure in raw ch — spend var(--measure)`);
+  }
+});
+
+test('the room head takes the display voice, and NOT the body measure', () => {
+  const h = rule(styleCss, '.page-head--room .page-head__h');
+  assert.ok(h, '.page-head--room .page-head__h has a rule');
+  assert.match(h, /font-family:\s*var\(--font-display\)/);
+  assert.doesNotMatch(h, /var\(--measure\)/,
+    '--measure is the BODY measure; on a display line it caps near 950px and the title runs the column');
+  const sub = rule(styleCss, '.page-head--room .page-head__sub');
+  assert.match(sub, /max-width:\s*var\(--measure\)/, 'the sub IS body prose, so it takes the measure');
+});
+
+// ---- 4. the room's one breakpoint is 760, and the script mirrors it --------
+
+test('the room and primer.js agree on 760px, exactly', () => {
+  assert.match(decomment(roomCss), /@media\s*\(max-width:\s*760px\)/,
+    'the room keeps its own breakpoint — narrowing it to the shell\'s 640 reopens the 641-760 band');
+  assert.match(primerJs, /matchMedia\('\(max-width:\s*760px\)'\)/,
+    'primer.js closes the contents at the same width the sheet collapses them');
+  assert.doesNotMatch(decomment(roomCss), /@media\s*\(max-width:\s*640px\)/,
+    'a second, narrower breakpoint in the room is the drift hall_audit exists to catch');
+});
+
+// ---- 5. one markdown parser -----------------------------------------------
+
+test('primer.js carries no parser of its own any more', () => {
+  for (const gone of ['function parseMarkdown', 'function splitTableRow', 'function renderInline', 'function slugify', 'function escapeHtml']) {
+    assert.ok(!primerJs.includes(gone),
+      `primer.js still defines ${gone} — that copy is md-reader.js's, and the copy is what dropped blockquotes`);
+  }
+  assert.match(primerJs, /window\.OTBMdReader/, 'primer.js renders through the shared reader');
+  assert.match(primerJs, /MD\.parseMarkdown\(md,\s*resolveLinkHref\)/, 'and passes its own link resolver into it');
+});
+
+test('primer.html loads the reader BEFORE the page script', () => {
+  // Positions of the SCRIPT TAGS, not of the filenames: the page's own comments
+  // name both files, and an indexOf over the raw HTML finds the prose first.
+  const srcs = [...primerHtml.matchAll(/<script[^>]+src="([^"?]+)/g)].map((m) => m[1]);
+  const reader = srcs.indexOf('/builders/md-reader.js');
+  const page = srcs.indexOf('/builders/primer.js');
+  assert.ok(reader > -1, 'primer.html loads md-reader.js');
+  assert.ok(reader < page, 'both are deferred, so document order is execution order — the reader has to be first');
+});
+
+test('the primer keeps the one rewrite that is its own', () => {
+  assert.match(primerJs, /drachmae-and-karma\.md.*\/builders\/drachmae/s,
+    'the economy doc has an in-hall reader page (task 1472); a link to it must stay in the hall, not bounce to GitHub');
+  assert.match(primerJs, /baseDir:\s*PRIMER_DIR/, 'and resolves its relative links against docs/onboarding/');
+});
+
+test('the room styles what the shared parser emits that the old copy never did', () => {
+  assert.match(mdReaderJs, /<blockquote>/, 'md-reader.js emits blockquotes');
+  const bq = rule(roomCss, '.primer-article blockquote');
+  assert.ok(bq, 'and the room has a rule for them — the pair IS the fix; either half alone is a silent no-op');
+  assert.match(bq, /var\(--glass\)/);
+});
+
+test('primer.js still injects the diagrams — the one parser-adjacent job that is the primer\'s', () => {
+  assert.match(primerJs, /function inlineDiagrams/);
+  assert.match(primerJs, /DIAGRAM_AT_HEADING/);
+  assert.match(primerJs, /fig\.className = 'primer-figure'/,
+    'the injected figure takes the class diagram-viewer.js upgrades and room.css frames');
+});
+
+// ---- 6. the soft gate is reachable ----------------------------------------
+
+test('the acknowledge gate is aria-disabled, never disabled', () => {
+  assert.match(primerHtml, /id="primer-ack-btn"[^>]*aria-disabled="true"/,
+    'a real disabled button leaves the tab order, so a keyboard reader never hears why it is locked');
+  assert.doesNotMatch(primerHtml, /id="primer-ack-btn"[^>]*\sdisabled(?:[=\s>])/, 'and carries no hard disabled attribute');
+  assert.doesNotMatch(primerJs, /btn\.disabled\s*=/, 'nor does the script set one');
+  assert.match(primerJs, /setAttribute\('aria-disabled'/, 'the lock is the aria state');
+  const locked = rule(primerCss, '.primer-ack__btn[aria-disabled="false"]');
+  assert.ok(locked, 'the sheet paints the OPEN state off the same attribute the script writes');
+  assert.match(locked, /background:\s*var\(--accent\)/, 'the accent lights only what is pressable');
+});
+
+test('the locked note is described to the control while it is locked, and dropped when it opens', () => {
+  assert.match(primerHtml, /aria-describedby="primer-ack-note-locked"/);
+  assert.match(primerJs, /removeAttribute\('aria-describedby'\)/,
+    'a note explaining a lock that is gone describes nothing');
+});
+
+// ---- 7. the diagram viewer -------------------------------------------------
+
+test('diagram-viewer.css carries no fallback for a token that cannot be missing', () => {
+  const hits = [...decomment(viewerCss).matchAll(/var\(\s*--[a-z-]+\s*,[^)]+\)/g)].map((m) => m[0]);
+  assert.deepEqual(hits, [],
+    'every one of these tokens ships in style.css, so the literal never rendered — it only encoded drift (the --ink fallback said #2a2a2a where the sheet ships #17181a)');
+});
+
+test('the viewer spends the named z rung, not a hand-written 9999', () => {
+  const full = rule(viewerCss, '.dgv.is-fullscreen');
+  assert.ok(full, '.dgv.is-fullscreen has a rule');
+  assert.match(full, /z-index:\s*var\(--z-diagram-full\)/);
+  assert.doesNotMatch(decomment(viewerCss), /z-index:\s*\d/, 'no bare number is left in the sheet');
+  assert.match(decomment(styleCss), /--z-diagram-full:\s*\d+/, 'and the rung is named in the shell ladder');
+});
+
+test('the fullscreen scroll lock is on the root, where the shell already locks', () => {
+  assert.match(decomment(viewerCss), /html\.dgv-fullscreen-open\s*\{\s*overflow:\s*hidden/);
+  assert.doesNotMatch(decomment(viewerCss), /body\.dgv-fullscreen-open/);
+  assert.match(viewerJs, /document\.documentElement\.classList\.toggle\('dgv-fullscreen-open'/,
+    'the script writes the class where the sheet reads it — the shell\'s own drawer uses html.drawer-open');
+  assert.match(decomment(styleCss), /html\.drawer-open/, 'and that is the convention it is matching');
+});
+
+test('the room frames BOTH figures the viewer upgrades', () => {
+  assert.match(viewerJs, /figure\.diagram img, figure\.primer-figure img/,
+    'one selector, two classes — the viewer has always treated them as one object');
+  const frame = decomment(roomCss).match(/\.primer-figure,\s*figure\.diagram\s*\{([^}]*)\}/);
+  assert.ok(frame, 'and the room frames them in one rule, so they cannot drift apart');
+  assert.match(frame[1], /var\(--glass\)/);
+  // the canvas is inserted INSIDE the figure, so exactly one of the two draws
+  // the frame or the diagram lands in nested boxes
+  const inner = decomment(roomCss).match(/\.primer-figure \.dgv,\s*figure\.diagram \.dgv\s*\{([^}]*)\}/);
+  assert.ok(inner, 'the inserted canvas gives up its own frame');
+  assert.match(inner[1], /border:\s*0/);
+});
+
+// ---- 8. every room has exactly one h1 -------------------------------------
+
+const ROOMS = [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['roadmap.html', roadmapHtml], ['ranks.html', ranksHtml]];
+
+// An HTML comment that mentions <h1> is prose, not markup — and these pages each
+// carry one explaining why the heading is there at all.
+const dehtmlcomment = (html) => html.replace(/<!--[\s\S]*?-->/g, '');
+
+test('every reading room renders exactly one h1, and it is the page head\'s', () => {
+  for (const [name, html] of ROOMS.map(([n, h]) => [n, dehtmlcomment(h)])) {
+    const h1s = [...html.matchAll(/<h1\b/g)];
+    assert.equal(h1s.length, 1, `${name} has exactly one <h1> — one-header-main-h1 measures the rendered DOM, not the happy path`);
+    assert.match(html, /<h1 class="page-head__h">/, `${name}'s h1 is the page head's`);
+  }
+});
+
+test('the three DOCS rooms take the room voice; the deck takes the board\'s', () => {
+  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['ranks.html', ranksHtml]]) {
+    assert.match(html, /class="page-head page-head--room"/, `${name} is a reading room`);
+    assert.match(html, /class="page-head__eyebrow"/, `${name} carries the room's eyebrow`);
+  }
+  assert.match(roadmapHtml, /class="page-head page-head--board"/,
+    'the roadmap is a working surface whose figures are the thing to look at, so its own name stays quiet');
+});
+
+test('the document\'s own h1 is suppressed, or the article would render a second one', () => {
+  const h1 = rule(roomCss, '.primer-article h1');
+  assert.ok(h1, 'room.css handles the markdown h1');
+  assert.match(h1, /display:\s*none/);
+});
+
+// ---- 9. the archetype's shape ---------------------------------------------
+
+test('the room opts in from its markup, and the archetype sheet is what carries it', () => {
+  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml]]) {
+    assert.match(html, /<body class="room[^"]*"/, `${name} opts into the room`);
+    assert.match(html, /href="\/builders\/room\.css"/, `${name} loads the archetype`);
+  }
+  const tokens = rule(roomCss, 'body.room');
+  assert.ok(tokens, 'the room\'s composition tokens are on the opt-in body class');
+  assert.doesNotMatch(tokens, /--measure\s*:/,
+    'the measure is NOT redeclared: a ch scales with the font size, so one measured token reads the same at 15px and 17px');
+});
+
+test('the room\'s panels are the shell\'s three card levels, not a fourth', () => {
+  for (const id of ['primer-article', 'primer-skeleton', 'primer-error', 'primer-ack']) {
+    assert.match(primerHtml, new RegExp(`class="[^"]*scroll"[^>]*id="${id}"|id="${id}"[^>]*class="[^"]*scroll"`),
+      `#${id} is the shell's .scroll — v3 has exactly three card levels and a fourth is a design decision, not a local override`);
+  }
+});
+
+test('no page sheet reaches into shell layout', () => {
+  for (const [name, css] of RESKINNED) {
+    assert.doesNotMatch(decomment(css), /\.app-content\s*>\s*main/,
+      `${name} overrides shell layout — the rule tests/hall_record_world.mjs pins`);
+  }
+});
+
+test('no reading room carries an inline <style>, and none needs an audit exception', () => {
+  const withStyle = ROOMS.filter(([, html]) => /<style[^>]*>[\s\S]*?\S[\s\S]*?<\/style>/.test(html)).map(([n]) => n);
+  assert.deepEqual(withStyle, [],
+    'diagrams.html held the hall\'s last SUBSTANTIVE one — 16 lines, one over the default budget, with its own hall_audit exception. The exception retired with it.');
+  const audit = fs.readFileSync(path.join(ROOT, 'tests', 'hall_audit.mjs'), 'utf8');
+  const budgets = audit.match(/const INLINE_STYLE_BUDGET = \{([\s\S]*?)\};/);
+  assert.ok(budgets, 'hall_audit.mjs still declares the ratchet');
+  assert.doesNotMatch(budgets[1].replace(/\/\/[^\n]*/g, ''), /['"][a-z-]+\.html['"]\s*:/,
+    'no page carries an inline-style exception any more');
+  // (scouting.html keeps a one-line block, comfortably inside the DEFAULT
+  // budget — an exception is what this asserts is gone, not every <style>.)
+});
+
+test('roadmap\'s two sub-24px controls clear the floor, on both axes', () => {
+  const t = rule(roadmapCss, '.rm-goal__t');
+  assert.ok(t, '.rm-goal__t has a rule');
+  assert.match(t, /min-height:\s*24px/, 'measured 20px: a 13px line box in a 7px row');
+  const more = rule(roadmapCss, '.rm-gmore');
+  assert.ok(more, '.rm-gmore has a rule');
+  assert.match(more, /min-height:\s*24px/, 'measured 19px');
+  // the WIDTH half is the one that gets missed: at 320 the four fixed items in
+  // the row ate it and `flex: 1; min-width: 0` resolved the title to 0x26
+  assert.match(decomment(roadmapCss), /@media\s*\(max-width:400px\)[\s\S]*?\.rm-goal__t\s*\{[^}]*flex:\s*1 0 100%/,
+    'and the row wraps before the title can resolve to zero width');
+});
+
+// ---- 10. the parser, actually run -----------------------------------------
+
+// md-reader.js is a browser IIFE that only touches `window` and `location`, so
+// a two-property sandbox is the whole DOM it needs.
+function loadReader() {
+  const sandbox = { window: {}, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/primer' } };
+  vm.createContext(sandbox);
+  vm.runInContext(mdReaderJs, sandbox, { filename: 'md-reader.js' });
+  return sandbox.window.OTBMdReader;
+}
+
+test('the shared parser renders the blockquote the primer\'s old copy dropped', () => {
+  const MD = loadReader();
+  const { html } = MD.parseMarkdown('> a note the primer used to lose\n', (h) => h);
+  assert.match(html, /<blockquote><p>a note the primer used to lose<\/p><\/blockquote>/);
+});
+
+test('it slugs h2s the way the table of contents and the in-doc anchors expect', () => {
+  const MD = loadReader();
+  const { html, headings } = MD.parseMarkdown('## The claim → ship lifecycle\n', (h) => h);
+  assert.equal(headings.length, 1);
+  assert.equal(headings[0].level, 2);
+  assert.equal(headings[0].id, MD.slugify('The claim → ship lifecycle'));
+  assert.match(html, new RegExp(`<h2 id="${headings[0].id}">`),
+    'the anchor in the markup and the id the TOC links to come from one call, so they cannot drift');
+});
+
+test('the primer\'s link resolver sends a repo-relative doc to GitHub and leaves the rest alone', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref({
+    baseDir: 'docs/onboarding/',
+    getBlobBase: () => 'https://github.com/o/r/blob/main',
+    getTreeBase: () => 'https://github.com/o/r/tree/main',
+  });
+  assert.equal(resolve('../../CLAUDE.md'), 'https://github.com/o/r/blob/main/CLAUDE.md');
+  assert.equal(resolve('../recipes/'), 'https://github.com/o/r/tree/main/docs/recipes');
+  assert.equal(resolve('#a-section'), '#a-section', 'an in-page anchor is left alone');
+  assert.equal(resolve('https://example.com/x'), 'https://example.com/x', 'so is an absolute URL');
+  assert.equal(resolve('diagrams'), '/builders/diagrams', 'and the diagrams index stays in the hall');
+});
+
+test('with no repo bases the resolver degrades instead of crashing the page', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' });
+  assert.equal(resolve('../../CLAUDE.md'), '../../CLAUDE.md',
+    'the bases are fetched at boot; before they land a relative href passes through and 404s harmlessly');
+});