@lovett/ui 0.0.11 → 0.2.0

package/src/__tests__/ranked-bars.test.tsx

@@ -0,0 +1,343 @@
+/**
+ * RankedBars — ADR-146 D5.
+ *
+ * What is pinned here is the arithmetic and the structure, not the paint.
+ * Three of these behaviours are the ones a "simplification" would quietly
+ * break:
+ *
+ *   1. **The track is bordered.** ADR-146's whole argument for this shape is
+ *      that a 3% row is unreadable without it. A refactor that drops the
+ *      border for a "cleaner" look loses the low-value rows and no other gate
+ *      can see it.
+ *   2. **The fold sums, it does not sample.** `topN` must fold the remainder
+ *      into one summed row, or the chart quietly under-reports.
+ *   3. **Degenerate data is a chart, not a crash.** Empty, all-zero, negative
+ *      and single-row inputs each have a documented answer (acceptance
+ *      criterion 8).
+ *
+ * `css: false` in the runner means imported stylesheets are not applied, but
+ * inline `style` attributes are — which is exactly what this primitive uses
+ * for colour and geometry, so `toHaveStyle` is meaningful here.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { RankedBars } from '../ranked-bars'
+
+const ITEMS = [
+  { key: 'direct', label: 'Direct', value: 200 },
+  { key: 'organic', label: 'Organic search', value: 800 },
+  { key: 'social', label: 'Social', value: 400 },
+]
+
+/** Row labels, top to bottom. */
+function labels(): string[] {
+  return screen
+    .getAllByRole('listitem')
+    .map((li) => li.querySelector('span')?.textContent ?? '')
+}
+
+/**
+ * The fill inside each track, top to bottom. The row is `[label/value row,
+ * track]`, and the track's only child is the fill — so `div:last-child > div`
+ * is the fill without needing a test-only attribute on the primitive.
+ */
+function fills(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('li > * > div:last-child > div'))
+}
+
+/** The bordered track of each row. */
+function tracks(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('li > * > div:last-child'))
+}
+
+describe('RankedBars ordering', () => {
+  it('sorts descending by default', () => {
+    render(<RankedBars items={ITEMS} />)
+    expect(labels()).toEqual(['Organic search', 'Social', 'Direct'])
+  })
+
+  it('sorts ascending on request', () => {
+    render(<RankedBars items={ITEMS} sort="asc" />)
+    expect(labels()).toEqual(['Direct', 'Social', 'Organic search'])
+  })
+
+  it('preserves caller order when sorting is off', () => {
+    render(<RankedBars items={ITEMS} sort="none" />)
+    expect(labels()).toEqual(['Direct', 'Organic search', 'Social'])
+  })
+
+  it('does not mutate the caller array', () => {
+    const items = [...ITEMS]
+    render(<RankedBars items={items} />)
+    expect(items.map((i) => i.key)).toEqual(['direct', 'organic', 'social'])
+  })
+})
+
+describe('RankedBars top-N fold', () => {
+  it('folds the remainder into one summed Other row', () => {
+    render(<RankedBars items={ITEMS} topN={1} />)
+    expect(labels()).toEqual(['Organic search', 'Other'])
+    // 400 + 200 — a fold sums, it never samples.
+    expect(screen.getByText('600')).toBeInTheDocument()
+  })
+
+  it('renames the folded row on request', () => {
+    render(<RankedBars items={ITEMS} topN={2} otherLabel="All other sources" />)
+    expect(labels()).toEqual(['Organic search', 'Social', 'All other sources'])
+  })
+
+  it('does not fold when there is nothing left over', () => {
+    render(<RankedBars items={ITEMS} topN={3} />)
+    expect(labels()).toHaveLength(3)
+    expect(screen.queryByText('Other')).not.toBeInTheDocument()
+  })
+
+  it('formats the folded sum through formatValue', () => {
+    render(<RankedBars items={ITEMS} topN={1} formatValue={(v) => `${v} visits`} />)
+    expect(screen.getByText('600 visits')).toBeInTheDocument()
+  })
+})
+
+describe('RankedBars fill widths', () => {
+  it('normalises against the largest row by default', () => {
+    const { container } = render(<RankedBars items={ITEMS} />)
+    expect(fills(container).map((el) => el.style.width)).toEqual(['100%', '50%', '25%'])
+  })
+
+  it('normalises against an explicit max when given', () => {
+    // 2000 = the true total, so the tracks read as share-of-total.
+    const { container } = render(<RankedBars items={ITEMS} max={2000} />)
+    expect(fills(container).map((el) => el.style.width)).toEqual(['40%', '20%', '10%'])
+  })
+
+  it('clamps a value above an explicit max to a full track', () => {
+    const { container } = render(<RankedBars items={ITEMS} max={100} />)
+    expect(fills(container).map((el) => el.style.width)).toEqual(['100%', '100%', '100%'])
+  })
+
+  it('yields empty tracks rather than dividing by zero on a non-positive max', () => {
+    const { container } = render(<RankedBars items={ITEMS} max={0} />)
+    expect(fills(container).map((el) => el.style.width)).toEqual(['0%', '0%', '0%'])
+  })
+})
+
+describe('RankedBars degenerate data', () => {
+  it('renders an empty list rather than crashing', () => {
+    render(<RankedBars items={[]} />)
+    expect(screen.getByRole('list')).toBeInTheDocument()
+    expect(screen.queryAllByRole('listitem')).toHaveLength(0)
+  })
+
+  it('renders a single row at a full track', () => {
+    const { container } = render(<RankedBars items={[{ key: 'a', label: 'A', value: 5 }]} />)
+    expect(fills(container).map((el) => el.style.width)).toEqual(['100%'])
+  })
+
+  it('renders an all-zero series as empty tracks, not a full one', () => {
+    const { container } = render(
+      <RankedBars
+        items={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B', value: 0 },
+        ]}
+      />,
+    )
+    expect(fills(container).map((el) => el.style.width)).toEqual(['0%', '0%'])
+  })
+
+  it('clamps a negative value to an empty track', () => {
+    const { container } = render(
+      <RankedBars
+        items={[
+          { key: 'a', label: 'A', value: 10 },
+          { key: 'b', label: 'B', value: -4 },
+        ]}
+      />,
+    )
+    expect(fills(container).map((el) => el.style.width)).toEqual(['100%', '0%'])
+  })
+
+  it('absorbs a non-finite value as zero rather than emitting NaN%', () => {
+    const { container } = render(
+      <RankedBars
+        items={[
+          { key: 'a', label: 'A', value: 10 },
+          { key: 'b', label: 'B', value: Number.NaN },
+        ]}
+      />,
+    )
+    const widths = fills(container).map((el) => el.style.width)
+    expect(widths).toEqual(['100%', '0%'])
+    expect(widths.join()).not.toContain('NaN')
+  })
+})
+
+describe('RankedBars structure', () => {
+  it('gives every track a border — the thing that makes a low row readable', () => {
+    const { container } = render(<RankedBars items={ITEMS} />)
+    for (const track of tracks(container)) {
+      expect(track.style.border).toBe('1px solid rgb(var(--border))')
+      expect(track.style.height).toBe('12px')
+      expect(track.style.borderRadius).toBe('var(--radius-full)')
+    }
+  })
+
+  it('honours a caller track height', () => {
+    const { container } = render(<RankedBars items={ITEMS} trackHeight={20} />)
+    expect(tracks(container)[0]?.style.height).toBe('20px')
+  })
+
+  it('divides every row after the first, and none when dividers are off', () => {
+    const { container, rerender } = render(<RankedBars items={ITEMS} />)
+    const divided = Array.from(container.querySelectorAll<HTMLElement>('li')).map(
+      (li) => li.style.borderTop,
+    )
+    expect(divided[0]).toBe('')
+    expect(divided[1]).toBe('1px solid rgb(var(--border))')
+    expect(divided[2]).toBe('1px solid rgb(var(--border))')
+
+    rerender(<RankedBars items={ITEMS} dividers={false} />)
+    for (const li of container.querySelectorAll<HTMLElement>('li')) {
+      expect(li.style.borderTop).toBe('')
+    }
+  })
+
+  it('fills with the accent by default and with a series slot when asked', () => {
+    const { container } = render(
+      <RankedBars
+        sort="none"
+        items={[
+          { key: 'a', label: 'A', value: 1 },
+          { key: 'b', label: 'B', value: 1, slot: 1 },
+          { key: 'c', label: 'C', value: 1, slot: 'other' },
+        ]}
+      />,
+    )
+    expect(fills(container).map((el) => el.style.background)).toEqual([
+      'rgb(var(--accent))',
+      'rgb(var(--series-2))',
+      'rgb(var(--text-muted))',
+    ])
+  })
+
+  it('tweens the fill with ease-out under motion-safe, never a spring', () => {
+    const { container } = render(<RankedBars items={ITEMS} />)
+    const fill = fills(container)[0]
+    expect(fill).toHaveClass('motion-safe:transition-[width,opacity]')
+    expect(fill?.style.transitionDuration).toBe('var(--dur-base)')
+    expect(fill?.style.transitionTimingFunction).toBe('var(--ease-out)')
+    expect(fill?.style.transitionTimingFunction).not.toContain('spring')
+  })
+
+  it('kills the transition outright under reduced motion', () => {
+    // The duration is inline and unconditional, and `transition-property`
+    // defaults to `all` — so without this class a reduce user gets MORE
+    // motion, not less. Every animated element in this primitive carries it.
+    const { container } = render(<RankedBars items={ITEMS} onSelect={() => {}} />)
+    for (const fill of fills(container)) {
+      expect(fill).toHaveClass('motion-reduce:transition-none')
+    }
+    for (const row of container.querySelectorAll<HTMLElement>('li > *')) {
+      expect(row).toHaveClass('motion-reduce:transition-none')
+    }
+  })
+
+  it('sets numbers in tabular figures and reserves the value column', () => {
+    const { container } = render(<RankedBars items={ITEMS} />)
+    const value = container.querySelector<HTMLElement>('li span:last-of-type')
+    expect(value).toHaveClass('tabular-nums')
+    expect(value?.style.minWidth).toBe('var(--space-12)')
+  })
+})
+
+describe('RankedBars interaction', () => {
+  it('is inert by default — no button advertises an absent interaction', () => {
+    render(<RankedBars items={ITEMS} />)
+    expect(screen.queryAllByRole('button')).toHaveLength(0)
+  })
+
+  it('reports the row key, not its index, when selected', async () => {
+    const onSelect = vi.fn()
+    render(<RankedBars items={ITEMS} onSelect={onSelect} />)
+    // Top row after the default descending sort is 'organic'.
+    await userEvent.click(screen.getAllByRole('button')[0] as HTMLElement)
+    expect(onSelect).toHaveBeenCalledWith('organic')
+  })
+
+  it('carries a visible focus ring on every interactive row', () => {
+    render(<RankedBars items={ITEMS} onSelect={() => {}} />)
+    for (const button of screen.getAllByRole('button')) {
+      expect(button).toHaveClass('focus-visible:[box-shadow:var(--ring-focus)]')
+    }
+  })
+
+  it('dims by opacity so an emphasis change cannot reflow the list', () => {
+    const { container } = render(<RankedBars items={ITEMS} activeKey="organic" />)
+    const rows = Array.from(container.querySelectorAll<HTMLElement>('li > div'))
+    // 0.7, not 0.55: at 0.55 a 14px --foreground label composites to 4.21:1 on
+    // a light card, under AA. A de-emphasized row is not a disabled one.
+    expect(rows.map((row) => row.style.opacity)).toEqual(['1', '0.7', '0.7'])
+  })
+
+  it('puts the rest of the de-emphasis on the mark, not on the label', () => {
+    const { container } = render(<RankedBars items={ITEMS} activeKey="organic" />)
+    expect(fills(container).map((el) => el.style.opacity)).toEqual(['1', '0.55', '0.55'])
+  })
+
+  it('shows a hover affordance on an interactive row', () => {
+    render(<RankedBars items={ITEMS} onSelect={() => {}} />)
+    for (const button of screen.getAllByRole('button')) {
+      expect(button).toHaveClass('hover:bg-[rgb(var(--surface-overlay))]')
+    }
+  })
+
+  it('claims aria-pressed only when the caller uses the emphasis model', () => {
+    const { rerender } = render(<RankedBars items={ITEMS} onSelect={() => {}} />)
+    // No activeKey prop at all: these are not toggles, and must not say they
+    // are. `null` means "the model is in use, nothing chosen yet".
+    for (const button of screen.getAllByRole('button')) {
+      expect(button).not.toHaveAttribute('aria-pressed')
+    }
+
+    rerender(<RankedBars items={ITEMS} onSelect={() => {}} activeKey={null} />)
+    for (const button of screen.getAllByRole('button')) {
+      expect(button).toHaveAttribute('aria-pressed', 'false')
+    }
+
+    rerender(<RankedBars items={ITEMS} onSelect={() => {}} activeKey="organic" />)
+    expect(screen.getAllByRole('button')[0]).toHaveAttribute('aria-pressed', 'true')
+  })
+
+  it('names the list for assistive tech', () => {
+    render(<RankedBars items={ITEMS} label="Traffic source" />)
+    expect(screen.getByRole('list', { name: 'Traffic source' })).toBeInTheDocument()
+  })
+})
+
+/**
+ * The label/value line here is the same shape as `ChartLegend`'s row — a
+ * `flex-1 min-w-0` label beside a `shrink-0` value with a reserved width —
+ * which is the shape that let `DonutChart`'s legend crush its labels to
+ * `width: 0` at a 390px viewport on 2026-09-06.
+ *
+ * Measured in a real browser at 390 / 900 / 1440 in both themes, the ranked
+ * rows themselves did NOT reproduce it: they are full-width, with no plot
+ * competing for the row, and no label came back at zero width or overflowing.
+ * The floor below is prophylactic, and only its MECHANISM is assertable here
+ * — jsdom has no layout, so it cannot show a crushed label either way.
+ */
+describe('RankedBars label floor (browser-measured: not reproduced, hardened)', () => {
+  it('floors the label width, bounds the floor, and keeps the full text recoverable', () => {
+    const { container } = render(<RankedBars items={ITEMS} />)
+    const labels = container.querySelectorAll<HTMLElement>('span[title]')
+    expect(labels.length).toBe(ITEMS.length)
+    for (const label of labels) {
+      expect(label.title).not.toBe('')
+      expect(label.style.minWidth).toBe('min(calc(var(--space-12) * 2), 100%)')
+      // The wrap is what makes the floor safe: the VALUE drops to a second
+      // line instead of the label giving up its width.
+      expect(label.parentElement?.className).toContain('flex-wrap')
+    }
+  })
+})

package/src/__tests__/remark-underline.test.ts

@@ -0,0 +1,194 @@
+/**
+ * remark-underline — the `++text++` tokenizer (ADR-148 D13).
+ *
+ * Drives the plugin through `react-markdown` exactly as the product does:
+ * `packages/ui` cannot import `unified` / `remark-parse` (transitives pnpm
+ * keeps out of reach — the same fact that makes the plugin hand-rolled), so
+ * `react-markdown` is the only door into the parser. `renderToStaticMarkup`
+ * with NO component overrides yields the bare hast as HTML, so every
+ * assertion here is about the tokenizer and the mdast handler, not styling.
+ *
+ * The marker is spelled as an escape (`PP`) throughout, per the test-file
+ * rule: the file never contains the syntax literally and stays plain UTF-8
+ * for the CLAUDE.md section 8 greps. Non-ASCII content is escaped for the same
+ * reason.
+ */
+
+import { createElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import { describe, expect, it } from 'vitest'
+import { remarkUnderline } from '../lib/remark-underline'
+import { MarkdownRenderer } from '../markdown'
+
+/** `++` — two U+002B PLUS SIGN. */
+const PP = '\u{2B}\u{2B}'
+const EMOJI = '\u{1F600}'
+const E_ACUTE = '\u{E9}'
+
+function html(markdown: string): string {
+  return renderToStaticMarkup(
+    createElement(ReactMarkdown, { remarkPlugins: [remarkGfm, remarkUnderline] }, markdown),
+  )
+}
+
+/** `[name, markdown, expected html]` — exact output, whitespace included. */
+type Case = readonly [name: string, input: string, expected: string]
+
+const HAPPY: readonly Case[] = [
+  ['a single run', `${PP}text${PP}`, '<p><u>text</u></p>'],
+  ['inside a sentence', `a ${PP}b${PP} c`, '<p>a <u>b</u> c</p>'],
+  ['two runs', `${PP}a${PP} and ${PP}b${PP}`, '<p><u>a</u> and <u>b</u></p>'],
+  ['at line start and line end', `${PP}start${PP} mid ${PP}end${PP}`, '<p><u>start</u> mid <u>end</u></p>'],
+  ['intraword', `foo${PP}bar${PP}baz`, '<p>foo<u>bar</u>baz</p>'],
+  ['multi-word content', `${PP}two words${PP}`, '<p><u>two words</u></p>'],
+  ['punctuation just inside the markers', `${PP}"x"${PP}`, '<p><u>&quot;x&quot;</u></p>'],
+  ['across a soft line break', `${PP}a\nb${PP}`, '<p><u>a\nb</u></p>'],
+  ['non-ascii content', `${PP}caf${E_ACUTE}${PP}`, `<p><u>caf${E_ACUTE}</u></p>`],
+  ['emoji directly after the closer', `${PP}x${PP}${EMOJI}`, `<p><u>x</u>${EMOJI}</p>`],
+  ['emoji directly before the opener', `${EMOJI}${PP}x${PP}`, `<p>${EMOJI}<u>x</u></p>`],
+  ['in a heading', `# ${PP}x${PP}`, '<h1><u>x</u></h1>'],
+  ['in a list item', `- ${PP}x${PP}`, '<ul>\n<li><u>x</u></li>\n</ul>'],
+  ['in a blockquote', `> ${PP}x${PP}`, '<blockquote>\n<p><u>x</u></p>\n</blockquote>'],
+]
+
+const LITERAL: readonly Case[] = [
+  ['an unclosed run', `${PP}unclosed`, `<p>${PP}unclosed</p>`],
+  ['a closer with no opener', `unopened${PP}`, `<p>unopened${PP}</p>`],
+  ['a lone marker pair', PP, `<p>${PP}</p>`],
+  ['a lone marker pair between words', `a ${PP} b`, `<p>a ${PP} b</p>`],
+  ['a space just inside the opener', `${PP} text${PP}`, `<p>${PP} text${PP}</p>`],
+  ['a space just inside the closer', `${PP}text ${PP}`, `<p>${PP}text ${PP}</p>`],
+  ['spaces just inside both', `${PP} text ${PP}`, `<p>${PP} text ${PP}</p>`],
+  ['a tab just inside the opener', `${PP}\ttext${PP}`, `<p>${PP}\ttext${PP}</p>`],
+  ['a single plus', '+x+', '<p>+x+</p>'],
+  ['three pluses', `+${PP}x+${PP}`, `<p>+${PP}x+${PP}</p>`],
+  ['an escaped opener', `\\${PP}x${PP}`, `<p>${PP}x${PP}</p>`],
+  ['C++ in prose', 'C++ and C++ again', '<p>C++ and C++ again</p>'],
+  ['an unclosed run followed by a real pair', `${PP}a ${PP}b${PP}`, `<p>${PP}a <u>b</u></p>`],
+]
+
+/**
+ * The flanking rule — identical to `~~` (and `**` minus the underscore
+ * exception): a run cannot open when it is preceded by a letter and followed
+ * by punctuation, and cannot close in the mirror case. The point is code in
+ * prose: this team writes `i++;` in comments.
+ */
+const FLANKING: readonly Case[] = [
+  ['i++; j++; stays literal', `i${PP}; j${PP};`, `<p>i${PP}; j${PP};</p>`],
+  ['post-increment in an assignment stays literal', `x = i${PP}; y = j${PP};`, `<p>x = i${PP}; y = j${PP};</p>`],
+  ['C++ alone stays literal', `C${PP}`, `<p>C${PP}</p>`],
+  ['C++ before punctuation stays literal', `C${PP}, C${PP}.`, `<p>C${PP}, C${PP}.</p>`],
+  ['closer-only runs stay literal', `a${PP} b${PP}`, `<p>a${PP} b${PP}</p>`],
+  ['opener-only runs stay literal', `${PP}a ${PP}b`, `<p>${PP}a ${PP}b</p>`],
+  // Intraword is allowed, exactly as `~~` and `**` allow it.
+  ['intraword underlines, like ~~ and **', `word${PP}x${PP}word`, `<p>word<u>x</u>word</p>`],
+  ['intraword with punctuation just inside stays literal, like ~~', `word${PP}"x"${PP}word`, `<p>word${PP}&quot;x&quot;${PP}word</p>`],
+  ['a parenthesised run after a letter stays literal', `a${PP}(note)${PP}b`, `<p>a${PP}(note)${PP}b</p>`],
+  ['a parenthesised run between spaces underlines', `see ${PP}(note)${PP} here`, `<p>see <u>(note)</u> here</p>`],
+  ['a run inside parentheses underlines', `(${PP}x${PP})`, `<p>(<u>x</u>)</p>`],
+  ['a run before a full stop underlines', `${PP}x${PP}.`, `<p><u>x</u>.</p>`],
+  ['a run inside quotes underlines', `"${PP}x${PP}"`, `<p>&quot;<u>x</u>&quot;</p>`],
+  ['a run after a colon underlines', `note: ${PP}x${PP}`, `<p>note: <u>x</u></p>`],
+]
+
+const CODE: readonly Case[] = [
+  ['inside a code span', `\`${PP}x${PP}\``, `<p><code>${PP}x${PP}</code></p>`],
+  ['inside a fence', `\`\`\`\n${PP}x${PP}\n\`\`\``, `<pre><code>${PP}x${PP}\n</code></pre>`],
+  ['inside an indented code block', `    ${PP}x${PP}`, `<pre><code>${PP}x${PP}\n</code></pre>`],
+  ['a code span inside the run', `${PP}a \`b\` c${PP}`, '<p><u>a <code>b</code> c</u></p>'],
+  ['a code span that itself holds the marker, inside a run', `${PP}a \`${PP}\` c${PP}`, `<p><u>a <code>${PP}</code> c</u></p>`],
+]
+
+const NESTING: readonly Case[] = [
+  ['inside strong', `**${PP}x${PP}**`, '<p><strong><u>x</u></strong></p>'],
+  ['around strong', `${PP}**x**${PP}`, '<p><u><strong>x</strong></u></p>'],
+  ['inside emphasis', `*${PP}x${PP}*`, '<p><em><u>x</u></em></p>'],
+  ['around emphasis', `${PP}*x*${PP}`, '<p><u><em>x</em></u></p>'],
+  ['inside strikethrough', `~~${PP}x${PP}~~`, '<p><del><u>x</u></del></p>'],
+  ['around strikethrough', `${PP}~~x~~${PP}`, '<p><u><del>x</del></u></p>'],
+  ['directly after strong', `**a**${PP}b${PP}`, '<p><strong>a</strong><u>b</u></p>'],
+  ['directly before strong', `${PP}a${PP}**b**`, '<p><u>a</u><strong>b</strong></p>'],
+  ['directly after strikethrough', `~~a~~${PP}b${PP}`, '<p><del>a</del><u>b</u></p>'],
+  ['directly before strikethrough', `${PP}a${PP}~~b~~`, '<p><u>a</u><del>b</del></p>'],
+  // Only passes because `+` is registered as an attention marker: without
+  // that, `**` followed by `+` is not left-flanking after a letter, and the
+  // output would be `a**<u>x</u>**b`.
+  ['intraword strong around a run', `a**${PP}x${PP}**b`, '<p>a<strong><u>x</u></strong>b</p>'],
+  // Strikethrough is the contrast: GFM's `~~` uses its own flanking rule and
+  // never reads attention markers, so after a letter and before punctuation it
+  // cannot open — plain GFM `a~~"x"~~b` behaves the same. The run inside
+  // still pairs; only the `~~` stays literal. Pinned, not a defect.
+  ['intraword strikethrough around a run', `a~~${PP}x${PP}~~b`, `<p>a~~<u>x</u>~~b</p>`],
+  ['strong and emphasis inside the run', `${PP}**a** and *b*${PP}`, '<p><u><strong>a</strong> and <em>b</em></u></p>'],
+  ['inside link text', `[${PP}x${PP}](https://example.com)`, '<p><a href="https://example.com"><u>x</u></a></p>'],
+  ['around a link', `${PP}[x](https://example.com)${PP}`, '<p><u><a href="https://example.com">x</a></u></p>'],
+  ['a marker in the link destination is not a run', '[x](https://example.com/a++b++c)', '<p><a href="https://example.com/a++b++c">x</a></p>'],
+  // Structural nesting of two pairs, exactly as `~~` behaves. The composer
+  // never emits it (marks cannot nest) and it renders as one underline; it is
+  // pinned so a future "fix" is a deliberate change, not drift.
+  ['two pairs nest structurally', `${PP}a ${PP}b${PP} c${PP}`, '<p><u>a <u>b</u> c</u></p>'],
+]
+
+function run(cases: readonly Case[]): void {
+  for (const [name, input, expected] of cases) {
+    it(name, () => {
+      expect(html(input)).toBe(expected)
+    })
+  }
+}
+
+describe('remarkUnderline', () => {
+  describe('renders a <u> for', () => run(HAPPY))
+  describe('stays literal text for', () => run(LITERAL))
+  describe('flanking, as ~~ does it', () => run(FLANKING))
+  describe('code', () => run(CODE))
+  describe('nesting with other inline constructs', () => run(NESTING))
+
+  describe('through MarkdownRenderer', () => {
+    it('renders the styled <u> from the shared component map', () => {
+      const out = renderToStaticMarkup(createElement(MarkdownRenderer, { children: `a ${PP}b${PP} c` }))
+      expect(out).toContain('<u class="underline-offset-2" style="color:rgb(var(--foreground));text-decoration-color:rgb(var(--text-tertiary))">b</u>')
+      expect(out).not.toContain(PP)
+    })
+  })
+
+  describe('does nothing without the plugin', () => {
+    it('leaves the markers as text', () => {
+      const bare = renderToStaticMarkup(
+        createElement(ReactMarkdown, { remarkPlugins: [remarkGfm] }, `${PP}x${PP}`),
+      )
+      expect(bare).toBe(`<p>${PP}x${PP}</p>`)
+    })
+  })
+
+  describe('bounded work on adversarial input', () => {
+    it('a 2,000-character line of closers with no opener stays literal', () => {
+      // Every run can close (preceded by `a`) and none can open (followed by
+      // a space): the resolver walks back from each of 500 closers.
+      const line = `a${PP} `.repeat(500)
+      expect(line).toHaveLength(2000)
+      expect(html(line)).toBe(`<p>${line.trimEnd()}</p>`)
+    })
+
+    it('a 2,000-character line of openers with no closer stays literal', () => {
+      const line = `${PP}a `.repeat(500)
+      expect(line).toHaveLength(2000)
+      expect(html(line)).toBe(`<p>${line.trimEnd()}</p>`)
+    })
+
+    it('a 2,000-character line of runs renders every one', () => {
+      // 333 six-character runs plus two trailing letters.
+      const line = `${PP}a${PP} `.repeat(333) + 'aa'
+      expect(line).toHaveLength(2000)
+      expect(html(line)).toBe(`<p>${'<u>a</u> '.repeat(333)}aa</p>`)
+    })
+
+    it('a 2,000-character run of bare markers stays literal', () => {
+      const line = PP.repeat(1000)
+      expect(line).toHaveLength(2000)
+      expect(html(line)).toBe(`<p>${line}</p>`)
+    })
+  })
+})