From b5dc392ca4317679ac8071b3a9a9e193e5d5c611 Mon Sep 17 00:00:00 2001
From: Art Pai <dev@starcoder.dev>
Date: Fri, 11 Sep 2026 22:12:05 +1000
Subject: [PATCH] Number review section titles beside the review map
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A section title carried no index, so a reader could not match the content being read with its entry in the review map. Both the title and the map now render the same zero-padded index from one shared sequence, and the title and explanation prose scale to 18px and 17px.

Co-Authored-By: ことね <kotone@claudecafe.dev>
---
 src/report/shell.ts | 15 +++++---
 test/report.test.ts | 86 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 5 deletions(-)

diff --git a/src/report/shell.ts b/src/report/shell.ts
index a0434ff..7fd021b 100644
--- a/src/report/shell.ts
+++ b/src/report/shell.ts
@@ -197,7 +197,7 @@ function renderSection(
 
   const markup = `<section class="section" id="${target.fragment}" data-section-index="${index}" data-target-kind="section">
   <details class="section-fold" open>
-    <summary class="section-title"><span class="section-title-text">${escapeHtml(section.title)}</span>${renderCopyLink(target.fragment, `Copy link to section ${section.title}`)}</summary>
+    <summary class="section-title"><span class="section-title-index">${sectionIndex(index)}</span><span class="section-title-text">${escapeHtml(section.title)}</span>${renderCopyLink(target.fragment, `Copy link to section ${section.title}`)}</summary>
 ${steps.join('\n')}
   </details>
 </section>`
@@ -212,7 +212,7 @@ function renderReviewMap(
   const links = sections
     .map(
       (section, index) =>
-        `<li><a href="#${section.fragment}"><span class="review-map-index">${String(index + 1).padStart(2, '0')}</span><span class="review-map-title">${escapeHtml(section.title)}</span></a></li>`,
+        `<li><a href="#${section.fragment}"><span class="review-map-index">${sectionIndex(index)}</span><span class="review-map-title">${escapeHtml(section.title)}</span></a></li>`,
     )
     .join('\n')
   return `<nav class="review-map" aria-label="Review map">
@@ -236,6 +236,10 @@ function pluralize(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? '' : 's'}`
 }
 
+function sectionIndex(index: number): string {
+  return String(index + 1).padStart(2, '0')
+}
+
 function renderSourceMetadata(source: ExplainDocument['source']): string {
   if (source.kind === 'commit-diff') {
     return `<dt>From</dt><dd>${renderEndpoint(source.from)}</dd>
@@ -403,11 +407,12 @@ main { max-width: none; min-width: 0; margin: 0; padding: 22px 28px 72px; }
   border-bottom: 1px solid transparent;
   color: #17271c;
   background: transparent;
-  font-size: 15px;
+  font-size: 18px;
   font-weight: 600;
   list-style: none;
   user-select: none;
 }
+.section-title-index { flex: none; color: var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .82em; font-weight: 600; }
 .section-title-text { min-width: 0; flex: 1; }
 .section-fold > summary::-webkit-details-marker { display: none; }
 .section-fold > summary::before { content: "▾ "; color: var(--accent); }
@@ -416,7 +421,7 @@ main { max-width: none; min-width: 0; margin: 0; padding: 22px 28px 72px; }
 .prose { color: #3c4d41; font-size: 14px; }
 .step { scroll-margin-top: 18px; }
 .step-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 5px; padding: 8px 12px 0; }
-.step-text { max-width: 900px; padding: 8px 20px; }
+.step-text { max-width: 900px; padding: 8px 20px; font-size: 17px; }
 .copy-link {
   padding: 3px 7px;
   border: 1px solid #c4d1c6;
@@ -558,7 +563,7 @@ main { max-width: none; min-width: 0; margin: 0; padding: 22px 28px 72px; }
   .report-cover h1 { font-size: 21px; }
   .layout-form label { padding: 4px 7px; font-size: 11px; }
   .fold-all { padding: 4px 7px; font-size: 11px; }
-  .section-fold > summary { font-size: 14px; }
+  .section-fold > summary { font-size: 17px; }
 }
 @media print {
   .layout-form, .copy-link { display: none; }
diff --git a/test/report.test.ts b/test/report.test.ts
index 1eb310e..c79eed7 100644
--- a/test/report.test.ts
+++ b/test/report.test.ts
@@ -411,6 +411,59 @@ describe('renderReport shell', () => {
     expect(html).toContain('>1 file<')
   })
 
+  test('section title indexes match the review map exactly from one section order', () => {
+    const html = renderReport(
+      document([
+        section(simplePatch('a', 'b'), 'First section'),
+        section(simplePatch('c', 'd'), 'Second section'),
+        section(simplePatch('e', 'f'), 'Third section'),
+      ]),
+      stubClient,
+    )
+
+    const titleIndexes = [
+      ...html.matchAll(/<span class="section-title-index">([^<]*)<\/span>/g),
+    ].map((match) => match[1])
+    const mapIndexes = [...html.matchAll(/<span class="review-map-index">([^<]*)<\/span>/g)].map(
+      (match) => match[1],
+    )
+
+    expect(titleIndexes).toEqual(['01', '02', '03'])
+    expect(mapIndexes).toEqual(titleIndexes)
+  })
+
+  test('section indexes stay complete above 99', () => {
+    const sections = Array.from({ length: 101 }, (_, index) => ({
+      title: `Section ${index + 1}`,
+      steps: [{ text: `Step ${index + 1}.` }],
+    }))
+    const html = renderReport(document(sections), stubClient)
+
+    const titleIndexes = [
+      ...html.matchAll(/<span class="section-title-index">([^<]*)<\/span>/g),
+    ].map((match) => match[1])
+    const mapIndexes = [...html.matchAll(/<span class="review-map-index">([^<]*)<\/span>/g)].map(
+      (match) => match[1],
+    )
+
+    expect(titleIndexes).toHaveLength(101)
+    expect(titleIndexes[99]).toBe('100')
+    expect(titleIndexes[100]).toBe('101')
+    expect(mapIndexes).toEqual(titleIndexes)
+  })
+
+  test('the section index is a distinct label that keeps the fold control and copy action', () => {
+    const html = renderReport(document([section(simplePatch(), 'Distinct')]), stubClient)
+
+    expect(html).toContain(
+      '<summary class="section-title"><span class="section-title-index">01</span><span class="section-title-text">Distinct</span><button type="button" class="copy-link"',
+    )
+    expect(html).toContain('.section-fold > summary::before { content: "▾ "; color: var(--accent); }')
+    expect(html).toContain(
+      '.section-title-index { flex: none; color: var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .82em; font-weight: 600; }',
+    )
+  })
+
   test('renders canonical copy actions without exposing renderer mounts as fragment IDs', () => {
     const value = document([
       {
@@ -456,6 +509,39 @@ describe('renderReport shell', () => {
     expect(html).toContain('overflow-wrap: anywhere;')
   })
 
+  test('section title and explanation prose use the exact scaled font sizes', () => {
+    const html = renderReport(document([section(simplePatch(), 'Scaled')]), stubClient)
+
+    const baseSummary = html.slice(
+      html.indexOf('.section-fold > summary {'),
+      html.indexOf('.section-fold > summary::-webkit-details-marker'),
+    )
+    expect(baseSummary).toContain('font-size: 18px;')
+
+    const narrowStart = html.indexOf('@media (max-width: 520px)')
+    const narrow = html.slice(narrowStart, html.indexOf('@media print', narrowStart))
+    expect(narrow).toContain('.section-fold > summary { font-size: 17px; }')
+
+    expect(html.match(/\.step-text \{/g)).toHaveLength(1)
+    expect(html).toContain('.step-text { max-width: 900px; padding: 8px 20px; font-size: 17px; }')
+  })
+
+  test('report-cover and diff typography keep their original font sizes', () => {
+    const html = renderReport(
+      document([section(simplePatch(), 'Unchanged')], { summary: 'Cover text stays put.' }),
+      stubClient,
+    )
+
+    expect(html).toContain('<div class="cover-summary prose">')
+    expect(html).toContain('<div class="step-text prose">')
+    expect(html).toContain('.prose { color: #3c4d41; font-size: 14px; }')
+    expect(html).toContain('font-size: 27px;')
+    expect(html).toContain('font-size: 21px;')
+    expect(html).toContain(
+      'font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 13px;',
+    )
+  })
+
   test('print output hides review map and layout controls and keeps source metadata', () => {
     const html = renderReport(document([section(simplePatch(), 'Print')]), stubClient)