From 6975ed4dc002ecf83c73db69d20938fe14b7cec2 Mon Sep 17 00:00:00 2001
From: Keith Smith <keithsmith@darksingularity.org>
Date: Fri, 2 Oct 2026 16:06:56 -0600
Subject: [PATCH] Add a collapsible markdown formatting toolbar to the composer
 (#75)

Markdown support was already complete and documented, but nothing in the
composer pointed at it -- unlike @, # and : (which advertise themselves
when typed), formatting syntax was only discoverable via Help, buried in
the account menu.

The composer stays a plain markdown textarea; a new "Aa" button opens a
toolbar that inserts the syntax for you: bold, italic, strikethrough,
inline code, code block, link, quote, bulleted/numbered lists, H1-H3,
sub/superscript. Collapsed by default, remembered across reloads and
room switches. Clicking a button again removes the formatting (native
undo doesn't track programmatic edits), and bold/italic/sub/strike
toggles are run-length aware so "***x***" is handled correctly. The
selection math is pure functions in lib/markdownFormat.ts, unit-tested.

The "?" opens /help#formatting in a new tab so the draft isn't lost;
HelpPage now scrolls to the hash once the guide has loaded, since the
browser's own hash scroll fired before the async-fetched headings
existed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 USER_GUIDE.md                                 |   8 +-
 frontend/src/components/Composer.css          |  28 +++
 frontend/src/components/Composer.tsx          |  42 ++++
 frontend/src/components/FormattingToolbar.css |  41 ++++
 .../src/components/FormattingToolbar.test.tsx |  55 +++++
 frontend/src/components/FormattingToolbar.tsx | 104 +++++++++
 .../src/lib/formattingToolbarPref.test.ts     |  31 +++
 frontend/src/lib/formattingToolbarPref.ts     |  21 ++
 frontend/src/lib/markdownFormat.test.ts       | 139 ++++++++++++
 frontend/src/lib/markdownFormat.ts            | 204 ++++++++++++++++++
 frontend/src/pages/HelpPage.tsx               |  11 +-
 11 files changed, 682 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/components/FormattingToolbar.css
 create mode 100644 frontend/src/components/FormattingToolbar.test.tsx
 create mode 100644 frontend/src/components/FormattingToolbar.tsx
 create mode 100644 frontend/src/lib/formattingToolbarPref.test.ts
 create mode 100644 frontend/src/lib/formattingToolbarPref.ts
 create mode 100644 frontend/src/lib/markdownFormat.test.ts
 create mode 100644 frontend/src/lib/markdownFormat.ts

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 3fb66aa..ee4bf8a 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -70,7 +70,13 @@ send. Use **Shift+Enter** to add a line break without sending.
 
 ## Formatting
 
-Messages support Markdown:
+Messages support Markdown. Prefer buttons to typing the syntax? Click the
+**Aa** button next to the emoji button in the composer to open a formatting
+toolbar — it inserts the markdown below into your message for you (select some
+text first to wrap it, or click a button again to take the formatting back
+off). It stays collapsed until you open it, and remembers your choice.
+
+Or type it yourself:
 
 - `**bold**`, `*italic*`, `~~strikethrough~~`
 - `` `inline code` `` and fenced code blocks (three backticks)
diff --git a/frontend/src/components/Composer.css b/frontend/src/components/Composer.css
index 1683f75..4736a26 100644
--- a/frontend/src/components/Composer.css
+++ b/frontend/src/components/Composer.css
@@ -105,6 +105,34 @@
   cursor: not-allowed;
 }
 
+.composer-format-toggle {
+  width: 36px;
+  height: 36px;
+  flex: none;
+  border-radius: var(--radius);
+  background: transparent;
+  color: var(--ds-muted);
+  border: 1px solid var(--ds-border);
+  font-size: 0.82rem;
+  font-weight: 700;
+  line-height: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.composer-format-toggle:hover:not(:disabled),
+.composer-format-toggle-open {
+  color: var(--ds-text);
+  border-color: var(--ds-accent);
+}
+
+.composer-format-toggle:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
 .composer-attach-wrap {
   position: relative;
   flex: none;
diff --git a/frontend/src/components/Composer.tsx b/frontend/src/components/Composer.tsx
index bbfbdf4..65e1cf0 100644
--- a/frontend/src/components/Composer.tsx
+++ b/frontend/src/components/Composer.tsx
@@ -15,10 +15,13 @@ import { getUploadLimit } from '../api/uploads'
 import { useCustomEmoji } from '../context/CustomEmojiContext'
 import { EMOJI_SHORTCODES, SHORTCODE_BY_GLYPH } from '../lib/emojiShortcodes'
 import { formatFileSize } from '../lib/fileSize'
+import { getFormattingToolbarOpen, setFormattingToolbarOpen } from '../lib/formattingToolbarPref'
+import { applyFormat, type FormatAction } from '../lib/markdownFormat'
 import { getRecentEmoji, recordEmojiUsed } from '../lib/recentEmoji'
 import type { MyRoomItem, RoomMember } from '../types'
 import { EmojiPicker } from './EmojiPicker'
 import { EmojiShortcodeAutocomplete, type EmojiShortcodeMatch } from './EmojiShortcodeAutocomplete'
+import { FormattingToolbar } from './FormattingToolbar'
 import { MentionAutocomplete } from './MentionAutocomplete'
 import { RoomReferenceAutocomplete } from './RoomReferenceAutocomplete'
 import './Composer.css'
@@ -136,6 +139,7 @@ export function Composer({ roomId, roomName, isDm, members, rooms, disabled, arc
   const [emojiActiveIndex, setEmojiActiveIndex] = useState(0)
   const [dragActive, setDragActive] = useState(false)
   const [attachMenuOpen, setAttachMenuOpen] = useState(false)
+  const [toolbarOpen, setToolbarOpen] = useState(getFormattingToolbarOpen)
   const { byShortcode: customEmojiByShortcode } = useCustomEmoji()
   const textareaRef = useRef<HTMLTextAreaElement>(null)
   const fileInputRef = useRef<HTMLInputElement>(null)
@@ -449,6 +453,29 @@ export function Composer({ roomId, roomName, isDm, members, rooms, disabled, arc
     })
   }
 
+  function toggleToolbar() {
+    const next = !toolbarOpen
+    setToolbarOpen(next)
+    setFormattingToolbarOpen(next)
+  }
+
+  // #75: the toolbar only ever edits the textarea's plain markdown text --
+  // nothing about what gets sent changes.
+  function applyFormatAction(action: FormatAction) {
+    const el = textareaRef.current
+    if (!el) return
+    const result = applyFormat(
+      { value, start: el.selectionStart ?? value.length, end: el.selectionEnd ?? value.length },
+      action,
+    )
+    setValue(result.value)
+    requestAnimationFrame(() => {
+      el.focus()
+      el.setSelectionRange(result.start, result.end)
+      autoGrow()
+    })
+  }
+
   function insertEmoji(emoji: string) {
     const el = textareaRef.current
     setEmojiPickerOpen(false)
@@ -517,6 +544,9 @@ export function Composer({ roomId, roomName, isDm, members, rooms, disabled, arc
         </div>
       )}
       {uploadError && <div className="composer-status composer-error">{uploadError}</div>}
+      {toolbarOpen && (
+        <FormattingToolbar id="composer-formatting-toolbar" disabled={isDisabled} onAction={applyFormatAction} />
+      )}
       <div className="composer-box">
         <input
           ref={photoInputRef}
@@ -589,6 +619,18 @@ export function Composer({ roomId, roomName, isDm, members, rooms, disabled, arc
             />
           )}
         </div>
+        <button
+          type="button"
+          className={`composer-format-toggle${toolbarOpen ? ' composer-format-toggle-open' : ''}`}
+          onClick={toggleToolbar}
+          disabled={isDisabled}
+          aria-label="Formatting options"
+          aria-expanded={toolbarOpen}
+          aria-controls="composer-formatting-toolbar"
+          title="Formatting options"
+        >
+          Aa
+        </button>
         <div className="composer-textarea-wrap">
           <textarea
             ref={textareaRef}
diff --git a/frontend/src/components/FormattingToolbar.css b/frontend/src/components/FormattingToolbar.css
new file mode 100644
index 0000000..5a024ef
--- /dev/null
+++ b/frontend/src/components/FormattingToolbar.css
@@ -0,0 +1,41 @@
+.formatting-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  /* Spacing, not divider lines, between groups -- a border on every group
+     after the first leaves a dangling line at the start of the second row
+     whenever the toolbar wraps on a narrow screen. */
+  gap: 2px 14px;
+}
+
+.formatting-toolbar-group {
+  display: flex;
+  gap: 2px;
+}
+
+.formatting-toolbar-btn {
+  min-width: 30px;
+  height: 30px;
+  padding: 0 6px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: none;
+  border-radius: 6px;
+  color: var(--ds-muted);
+  font-size: 0.82rem;
+  line-height: 1;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.formatting-toolbar-btn:hover:not(:disabled) {
+  background: var(--ds-surface-2);
+  color: var(--ds-text);
+}
+
+.formatting-toolbar-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
diff --git a/frontend/src/components/FormattingToolbar.test.tsx b/frontend/src/components/FormattingToolbar.test.tsx
new file mode 100644
index 0000000..b52ab6f
--- /dev/null
+++ b/frontend/src/components/FormattingToolbar.test.tsx
@@ -0,0 +1,55 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { FormatAction } from '../lib/markdownFormat'
+import { FormattingToolbar } from './FormattingToolbar'
+
+afterEach(cleanup)
+
+const EXPECTED: [string, FormatAction][] = [
+  ['Bold', { kind: 'inline', marker: '**' }],
+  ['Italic', { kind: 'inline', marker: '*' }],
+  ['Strikethrough', { kind: 'inline', marker: '~~' }],
+  ['Inline code', { kind: 'inline', marker: '`' }],
+  ['Code block', { kind: 'codeBlock' }],
+  ['Link', { kind: 'link' }],
+  ['Quote', { kind: 'prefix', prefix: 'quote' }],
+  ['Bulleted list', { kind: 'prefix', prefix: 'bullet' }],
+  ['Numbered list', { kind: 'prefix', prefix: 'ordered' }],
+  ['Heading 1', { kind: 'heading', level: 1 }],
+  ['Heading 2', { kind: 'heading', level: 2 }],
+  ['Heading 3', { kind: 'heading', level: 3 }],
+  ['Subscript', { kind: 'inline', marker: '~' }],
+  ['Superscript', { kind: 'inline', marker: '^' }],
+]
+
+describe('FormattingToolbar', () => {
+  it.each(EXPECTED)('%s button calls onAction with its action', (label, action) => {
+    const onAction = vi.fn()
+    render(<FormattingToolbar id="t" onAction={onAction} />)
+    fireEvent.click(screen.getByRole('button', { name: label }))
+    expect(onAction).toHaveBeenCalledTimes(1)
+    expect(onAction).toHaveBeenCalledWith(action)
+  })
+
+  it('disables every button when disabled, but leaves the help link usable', () => {
+    render(<FormattingToolbar id="t" disabled onAction={vi.fn()} />)
+    const buttons = screen.getAllByRole('button') as HTMLButtonElement[]
+    expect(buttons).toHaveLength(EXPECTED.length)
+    expect(buttons.every((b) => b.disabled)).toBe(true)
+    expect(screen.getByRole('link', { name: 'Formatting help' })).toBeTruthy()
+  })
+
+  it('opens help in a new tab so the draft in the composer is not lost', () => {
+    render(<FormattingToolbar id="t" onAction={vi.fn()} />)
+    const help = screen.getByRole('link', { name: 'Formatting help' })
+    expect(help.getAttribute('href')).toBe('/help#formatting')
+    expect(help.getAttribute('target')).toBe('_blank')
+    expect(help.getAttribute('rel')).toContain('noopener')
+  })
+
+  it('keeps focus in the textarea by cancelling mousedown on buttons', () => {
+    render(<FormattingToolbar id="t" onAction={vi.fn()} />)
+    // fireEvent returns false when the event's default was prevented.
+    expect(fireEvent.mouseDown(screen.getByRole('button', { name: 'Bold' }))).toBe(false)
+  })
+})
diff --git a/frontend/src/components/FormattingToolbar.tsx b/frontend/src/components/FormattingToolbar.tsx
new file mode 100644
index 0000000..92f3d72
--- /dev/null
+++ b/frontend/src/components/FormattingToolbar.tsx
@@ -0,0 +1,104 @@
+import type { ReactNode } from 'react'
+import type { FormatAction, InlineMarker } from '../lib/markdownFormat'
+import './FormattingToolbar.css'
+
+interface FormattingToolbarProps {
+  id: string
+  disabled?: boolean
+  onAction: (action: FormatAction) => void
+}
+
+interface ToolbarButton {
+  label: string
+  // Shows the syntax the button inserts -- the toolbar doubles as the
+  // "quick guide" for people who'd rather learn to type it themselves.
+  title: string
+  content: ReactNode
+  action: FormatAction
+}
+
+const inline = (marker: InlineMarker): FormatAction => ({ kind: 'inline', marker })
+
+const GROUPS: ToolbarButton[][] = [
+  [
+    { label: 'Bold', title: 'Bold: **text**', content: <b>B</b>, action: inline('**') },
+    { label: 'Italic', title: 'Italic: *text*', content: <i>I</i>, action: inline('*') },
+    { label: 'Strikethrough', title: 'Strikethrough: ~~text~~', content: <s>S</s>, action: inline('~~') },
+  ],
+  [
+    { label: 'Inline code', title: 'Inline code: `code`', content: '</>', action: inline('`') },
+    { label: 'Code block', title: 'Code block: ``` on its own lines', content: '{ }', action: { kind: 'codeBlock' } },
+  ],
+  [
+    {
+      label: 'Link',
+      title: 'Link: [text](url)',
+      content: (
+        <svg width="15" height="15" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+          <path
+            d="M8.5 11.5a3 3 0 0 0 4.2 0l2.6-2.6a3 3 0 0 0-4.2-4.2l-.9.9M11.5 8.5a3 3 0 0 0-4.2 0l-2.6 2.6a3 3 0 0 0 4.2 4.2l.9-.9"
+            stroke="currentColor"
+            strokeWidth="1.6"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      ),
+      action: { kind: 'link' },
+    },
+    { label: 'Quote', title: 'Quote: > text', content: '“', action: { kind: 'prefix', prefix: 'quote' } },
+  ],
+  [
+    { label: 'Bulleted list', title: 'Bulleted list: - item', content: '•', action: { kind: 'prefix', prefix: 'bullet' } },
+    { label: 'Numbered list', title: 'Numbered list: 1. item', content: '1.', action: { kind: 'prefix', prefix: 'ordered' } },
+  ],
+  [
+    { label: 'Heading 1', title: 'Heading 1: # text', content: 'H1', action: { kind: 'heading', level: 1 } },
+    { label: 'Heading 2', title: 'Heading 2: ## text', content: 'H2', action: { kind: 'heading', level: 2 } },
+    { label: 'Heading 3', title: 'Heading 3: ### text', content: 'H3', action: { kind: 'heading', level: 3 } },
+  ],
+  [
+    { label: 'Subscript', title: 'Subscript: ~text~ (no spaces)', content: 'x₂', action: inline('~') },
+    { label: 'Superscript', title: 'Superscript: ^text^ (no spaces)', content: 'x²', action: inline('^') },
+  ],
+]
+
+export function FormattingToolbar({ id, disabled, onAction }: FormattingToolbarProps) {
+  return (
+    <div id={id} className="formatting-toolbar" role="toolbar" aria-label="Formatting">
+      {GROUPS.map((group) => (
+        <div key={group[0].label} className="formatting-toolbar-group">
+          {group.map((button) => (
+            <button
+              key={button.label}
+              type="button"
+              className="formatting-toolbar-btn"
+              title={button.title}
+              aria-label={button.label}
+              disabled={disabled}
+              // Keeps focus (and the selection) in the textarea -- a click
+              // on a button would otherwise blur it, and on mobile dismiss
+              // the keyboard.
+              onMouseDown={(e) => e.preventDefault()}
+              onClick={() => onAction(button.action)}
+            >
+              {button.content}
+            </button>
+          ))}
+        </div>
+      ))}
+      {/* A new tab on purpose: the draft lives in Composer's own state, so
+          navigating this one away would lose it. */}
+      <a
+        className="formatting-toolbar-btn formatting-toolbar-help"
+        href="/help#formatting"
+        target="_blank"
+        rel="noopener noreferrer"
+        title="Formatting help (opens in a new tab)"
+        aria-label="Formatting help"
+      >
+        ?
+      </a>
+    </div>
+  )
+}
diff --git a/frontend/src/lib/formattingToolbarPref.test.ts b/frontend/src/lib/formattingToolbarPref.test.ts
new file mode 100644
index 0000000..9d363d3
--- /dev/null
+++ b/frontend/src/lib/formattingToolbarPref.test.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getFormattingToolbarOpen, setFormattingToolbarOpen } from './formattingToolbarPref'
+
+afterEach(() => {
+  localStorage.clear()
+  vi.restoreAllMocks()
+})
+
+describe('formatting toolbar preference', () => {
+  it('is collapsed by default', () => {
+    expect(getFormattingToolbarOpen()).toBe(false)
+  })
+
+  it('remembers being opened and closed', () => {
+    setFormattingToolbarOpen(true)
+    expect(getFormattingToolbarOpen()).toBe(true)
+    setFormattingToolbarOpen(false)
+    expect(getFormattingToolbarOpen()).toBe(false)
+  })
+
+  it('falls back to collapsed when storage is unavailable', () => {
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('blocked')
+    })
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new Error('blocked')
+    })
+    expect(getFormattingToolbarOpen()).toBe(false)
+    expect(() => setFormattingToolbarOpen(true)).not.toThrow()
+  })
+})
diff --git a/frontend/src/lib/formattingToolbarPref.ts b/frontend/src/lib/formattingToolbarPref.ts
new file mode 100644
index 0000000..3a89846
--- /dev/null
+++ b/frontend/src/lib/formattingToolbarPref.ts
@@ -0,0 +1,21 @@
+const KEY = 'ds-chat-formatting-toolbar-open'
+
+// Collapsed unless the user has opened it before -- and remembered, because
+// Composer remounts on every room switch and would otherwise snap shut each
+// time.
+export function getFormattingToolbarOpen(): boolean {
+  try {
+    return localStorage.getItem(KEY) === 'true'
+  } catch {
+    return false
+  }
+}
+
+export function setFormattingToolbarOpen(open: boolean): void {
+  try {
+    localStorage.setItem(KEY, String(open))
+  } catch {
+    // storage unavailable (private browsing, quota) -- the toolbar just
+    // won't remember its state, not fatal.
+  }
+}
diff --git a/frontend/src/lib/markdownFormat.test.ts b/frontend/src/lib/markdownFormat.test.ts
new file mode 100644
index 0000000..185110d
--- /dev/null
+++ b/frontend/src/lib/markdownFormat.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+import { applyFormat, type FormatAction, type InlineMarker, type TextState } from './markdownFormat'
+
+// ⟦ and ⟧ mark the selection, so cases read as plain strings -- an empty
+// pair (⟦⟧) is a bare cursor.
+const L = '⟦'
+const R = '⟧'
+
+function parse(s: string): TextState {
+  const start = s.indexOf(L)
+  const end = s.indexOf(R) - 1
+  return { value: s.replace(L, '').replace(R, ''), start, end }
+}
+
+function render({ value, start, end }: TextState): string {
+  return value.slice(0, start) + L + value.slice(start, end) + R + value.slice(end)
+}
+
+function fmt(s: string, action: FormatAction): string {
+  return render(applyFormat(parse(s), action))
+}
+
+const inline = (marker: InlineMarker): FormatAction => ({ kind: 'inline', marker })
+
+describe('inline wrap', () => {
+  it('wraps the selection and keeps the inner text selected', () => {
+    expect(fmt('say ⟦hi⟧ now', inline('**'))).toBe('say **⟦hi⟧** now')
+  })
+
+  it('inserts an empty pair with the cursor between when nothing is selected', () => {
+    expect(fmt('say ⟦⟧now', inline('**'))).toBe('say **⟦⟧**now')
+  })
+
+  it('unwraps when the markers sit just outside the selection', () => {
+    expect(fmt('say **⟦hi⟧** now', inline('**'))).toBe('say ⟦hi⟧ now')
+  })
+
+  it('unwraps when the selection includes the markers', () => {
+    expect(fmt('say ⟦**hi**⟧ now', inline('**'))).toBe('say ⟦hi⟧ now')
+  })
+
+  it('keeps markers outside leading/trailing whitespace in the selection', () => {
+    expect(fmt('a⟦ hi ⟧b', inline('**'))).toBe('a **⟦hi⟧** b')
+  })
+
+  it('italic on a bold selection adds italic rather than stripping bold', () => {
+    expect(fmt('x **⟦hi⟧** y', inline('*'))).toBe('x ***⟦hi⟧*** y')
+  })
+
+  it('removes just bold from bold+italic', () => {
+    expect(fmt('x ***⟦hi⟧*** y', inline('**'))).toBe('x *⟦hi⟧* y')
+  })
+
+  it('removes just italic from bold+italic', () => {
+    expect(fmt('x ***⟦hi⟧*** y', inline('*'))).toBe('x **⟦hi⟧** y')
+  })
+
+  it('strikethrough toggles off without being confused by subscript', () => {
+    expect(fmt('x ~~⟦hi⟧~~ y', inline('~~'))).toBe('x ⟦hi⟧ y')
+    expect(fmt('a ⟦hi⟧ b', inline('~'))).toBe('a ~⟦hi⟧~ b')
+  })
+
+  it('handles inline code and superscript', () => {
+    expect(fmt('run ⟦ls⟧', inline('`'))).toBe('run `⟦ls⟧`')
+    expect(fmt('x⟦2⟧', inline('^'))).toBe('x^⟦2⟧^')
+  })
+
+  it.each(['**', '*', '~~', '~', '`', '^'] as InlineMarker[])('%s: applying twice restores the original', (marker) => {
+    const original = parse('a ⟦b⟧ c')
+    const once = applyFormat(original, inline(marker))
+    expect(once.value).not.toBe(original.value)
+    expect(applyFormat(once, inline(marker))).toEqual(original)
+  })
+})
+
+describe('line prefixes', () => {
+  it('prefixes the current line and moves the cursor with it', () => {
+    expect(fmt('hello⟦⟧', { kind: 'prefix', prefix: 'quote' })).toBe('> hello⟦⟧')
+    expect(fmt('one\ntw⟦⟧o', { kind: 'prefix', prefix: 'quote' })).toBe('one\n> tw⟦⟧o')
+  })
+
+  it('starts a list on a blank line', () => {
+    expect(fmt('⟦⟧', { kind: 'prefix', prefix: 'bullet' })).toBe('- ⟦⟧')
+  })
+
+  it('prefixes every selected line, then toggles them back off', () => {
+    const bullet: FormatAction = { kind: 'prefix', prefix: 'bullet' }
+    expect(fmt('⟦a\nb⟧', bullet)).toBe('⟦- a\n- b⟧')
+    expect(fmt('⟦- a\n- b⟧', bullet)).toBe('⟦a\nb⟧')
+  })
+
+  it('numbers lines sequentially, skipping blank lines, and renumbers existing numbers', () => {
+    const ordered: FormatAction = { kind: 'prefix', prefix: 'ordered' }
+    expect(fmt('⟦a\n\nb⟧', ordered)).toBe('⟦1. a\n\n2. b⟧')
+    expect(fmt('⟦1. a\nb⟧', ordered)).toBe('⟦1. a\n2. b⟧')
+    expect(fmt('⟦1. a\n2. b⟧', ordered)).toBe('⟦a\nb⟧')
+  })
+
+  it('does not include a line the selection only touches at its very start', () => {
+    expect(fmt('a\n⟦b\n⟧c', { kind: 'prefix', prefix: 'bullet' })).toBe('a\n⟦- b⟧\nc')
+  })
+})
+
+describe('headings', () => {
+  it('adds, replaces, and toggles off the heading level', () => {
+    expect(fmt('title⟦⟧', { kind: 'heading', level: 2 })).toBe('## title⟦⟧')
+    expect(fmt('⟦# hi⟧', { kind: 'heading', level: 2 })).toBe('⟦## hi⟧')
+    expect(fmt('⟦## hi⟧', { kind: 'heading', level: 1 })).toBe('⟦# hi⟧')
+    expect(fmt('⟦## hi⟧', { kind: 'heading', level: 2 })).toBe('⟦hi⟧')
+  })
+})
+
+describe('code block', () => {
+  it('inserts an empty fenced block with the cursor on the blank line', () => {
+    expect(fmt('⟦⟧', { kind: 'codeBlock' })).toBe('```\n⟦⟧\n```')
+  })
+
+  it('puts the fences on their own lines when the selection is mid-line', () => {
+    expect(fmt('see ⟦x = 1⟧ here', { kind: 'codeBlock' })).toBe('see \n```\n⟦x = 1⟧\n```\n here')
+  })
+
+  it('does not double the newline when the selection already ends with one', () => {
+    expect(fmt('⟦a\n⟧b', { kind: 'codeBlock' })).toBe('```\n⟦a⟧\n```\nb')
+  })
+})
+
+describe('link', () => {
+  it('wraps the selection and selects the placeholder url', () => {
+    expect(fmt('see ⟦docs⟧', { kind: 'link' })).toBe('see [docs](⟦url⟧)')
+  })
+
+  it('treats a selected url as the target and leaves the cursor in the text brackets', () => {
+    expect(fmt('⟦https://example.com⟧', { kind: 'link' })).toBe('[⟦⟧](https://example.com)')
+  })
+
+  it('inserts a placeholder link with its text selected when nothing is selected', () => {
+    expect(fmt('a ⟦⟧', { kind: 'link' })).toBe('a [⟦link text⟧](url)')
+  })
+})
diff --git a/frontend/src/lib/markdownFormat.ts b/frontend/src/lib/markdownFormat.ts
new file mode 100644
index 0000000..e05eb33
--- /dev/null
+++ b/frontend/src/lib/markdownFormat.ts
@@ -0,0 +1,204 @@
+// #75: pure text transforms behind the composer's formatting toolbar. Each
+// takes the textarea's value plus its selection and returns the same shape,
+// so Composer just applies the result -- keeping this free of React/DOM is
+// what makes the fiddly selection math directly unit-testable.
+export interface TextState {
+  value: string
+  start: number
+  end: number
+}
+
+export type InlineMarker = '**' | '*' | '~~' | '`' | '~' | '^'
+
+export type FormatAction =
+  | { kind: 'inline'; marker: InlineMarker }
+  | { kind: 'prefix'; prefix: 'quote' | 'bullet' | 'ordered' }
+  | { kind: 'heading'; level: 1 | 2 | 3 }
+  | { kind: 'codeBlock' }
+  | { kind: 'link' }
+
+// Markers whose doubled form is a *different* format (`**` bold vs `*`
+// italic, `~~` strikethrough vs `~` subscript), so "is this already
+// wrapped?" has to look at how long the run of marker characters is rather
+// than just whether one is present.
+const DOUBLED_IS_DIFFERENT = new Set(['*', '~'])
+
+// A run of 3 `*` is bold+italic: bold (2) and italic (1) are both "present".
+function hasMarker(marker: string, run: number): boolean {
+  if (marker.length === 2) return run >= 2
+  return DOUBLED_IS_DIFFERENT.has(marker[0]) ? run % 2 === 1 : run >= 1
+}
+
+function applyInline(state: TextState, marker: InlineMarker): TextState {
+  const { value, start, end } = state
+  const ch = marker[0]
+  const m = marker.length
+  const sel = value.slice(start, end)
+
+  // Selection includes the markers themselves (e.g. the user selected the
+  // whole `**word**`) -- unwrap inside the selection.
+  if (sel.length > 0) {
+    let lead = 0
+    while (lead < sel.length && sel[lead] === ch) lead++
+    let trail = 0
+    while (trail < sel.length - lead && sel[sel.length - 1 - trail] === ch) trail++
+    const run = Math.min(lead, trail)
+    if (run > 0 && hasMarker(marker, run) && sel.length > 2 * m) {
+      const inner = sel.slice(m, sel.length - m)
+      return { value: value.slice(0, start) + inner + value.slice(end), start, end: start + inner.length }
+    }
+  }
+
+  // Markers sit just outside the selection. Skipped when the selection has
+  // edge whitespace: markers adjacent to it belong to neighbouring spans
+  // (`*a* and *b*` with " and " selected), not to this selection.
+  const edgeWhitespace = sel.length > 0 && (/^\s/.test(sel) || /\s$/.test(sel))
+  if (!edgeWhitespace) {
+    let before = 0
+    while (start - before - 1 >= 0 && value[start - before - 1] === ch) before++
+    let after = 0
+    while (end + after < value.length && value[end + after] === ch) after++
+    const run = Math.min(before, after)
+    if (run > 0 && hasMarker(marker, run)) {
+      return {
+        value: value.slice(0, start - m) + sel + value.slice(end + m),
+        start: start - m,
+        end: end - m,
+      }
+    }
+  }
+
+  // Nothing selected (or only whitespace): drop in an empty pair, cursor between.
+  if (sel.trim() === '') {
+    return {
+      value: value.slice(0, start) + marker + marker + value.slice(start),
+      start: start + m,
+      end: start + m,
+    }
+  }
+
+  // Markdown doesn't treat `** word**` as bold -- keep the markers hugging
+  // the text, outside any whitespace the selection happens to include.
+  const innerStart = start + (sel.length - sel.trimStart().length)
+  const innerEnd = end - (sel.length - sel.trimEnd().length)
+  return {
+    value:
+      value.slice(0, innerStart) + marker + value.slice(innerStart, innerEnd) + marker + value.slice(innerEnd),
+    start: innerStart + m,
+    end: innerEnd + m,
+  }
+}
+
+// The whole lines a selection touches. A selection that ends right after a
+// newline (i.e. at the very start of the next line) doesn't count that line.
+function lineBounds(value: string, start: number, end: number) {
+  const lineStart = start === 0 ? 0 : value.lastIndexOf('\n', start - 1) + 1
+  const effectiveEnd = end > start && value[end - 1] === '\n' ? end - 1 : end
+  const nextNewline = value.indexOf('\n', effectiveEnd)
+  return { lineStart, lineEnd: nextNewline === -1 ? value.length : nextNewline }
+}
+
+function transformLines(state: TextState, transform: (lines: string[]) => string[]): TextState {
+  const { value, start, end } = state
+  const { lineStart, lineEnd } = lineBounds(value, start, end)
+  const oldBlock = value.slice(lineStart, lineEnd)
+  const newBlock = transform(oldBlock.split('\n')).join('\n')
+  const next = value.slice(0, lineStart) + newBlock + value.slice(lineEnd)
+  if (start === end) {
+    const cursor = Math.max(lineStart, start + (newBlock.length - oldBlock.length))
+    return { value: next, start: cursor, end: cursor }
+  }
+  // Keep the affected lines selected so the same button toggles it back off.
+  return { value: next, start: lineStart, end: lineStart + newBlock.length }
+}
+
+const ORDERED_RE = /^\d+\. /
+
+function applyPrefix(state: TextState, kind: 'quote' | 'bullet' | 'ordered'): TextState {
+  const marker = kind === 'quote' ? '> ' : '- '
+  const has = (line: string) => (kind === 'ordered' ? ORDERED_RE.test(line) : line.startsWith(marker))
+  const strip = (line: string) => (kind === 'ordered' ? line.replace(ORDERED_RE, '') : line.slice(marker.length))
+
+  return transformLines(state, (lines) => {
+    // Blank lines inside a multi-line selection are paragraph breaks, not
+    // list items -- only a lone blank line (cursor on an empty line) gets one.
+    const multi = lines.length > 1
+    const skip = (line: string) => multi && line === ''
+    const targets = lines.filter((line) => !skip(line))
+    if (targets.length > 0 && targets.every(has)) {
+      return lines.map((line) => (has(line) ? strip(line) : line))
+    }
+    let n = 0
+    return lines.map((line) => {
+      if (skip(line)) return line
+      n++
+      if (kind === 'ordered') return `${n}. ${strip(line)}`
+      return has(line) ? line : marker + line
+    })
+  })
+}
+
+const HEADING_RE = /^#{1,6} /
+
+function applyHeading(state: TextState, level: 1 | 2 | 3): TextState {
+  const prefix = '#'.repeat(level) + ' '
+  return transformLines(state, (lines) => {
+    const multi = lines.length > 1
+    const skip = (line: string) => multi && line === ''
+    const targets = lines.filter((line) => !skip(line))
+    if (targets.length > 0 && targets.every((line) => line.startsWith(prefix))) {
+      return lines.map((line) => (line.startsWith(prefix) ? line.slice(prefix.length) : line))
+    }
+    return lines.map((line) => (skip(line) ? line : prefix + line.replace(HEADING_RE, '')))
+  })
+}
+
+// A fence only counts at the start of a line, so mid-line cursors get a
+// newline inserted first.
+function applyCodeBlock(state: TextState): TextState {
+  const { value, start, end } = state
+  const before = value.slice(0, start)
+  const after = value.slice(end)
+  const sel = value.slice(start, end).replace(/\n$/, '')
+  const lead = before.length > 0 && !before.endsWith('\n') ? '\n' : ''
+  const trail = after.length > 0 && !after.startsWith('\n') ? '\n' : ''
+  const next = `${before}${lead}\`\`\`\n${sel}\n\`\`\`${trail}${after}`
+  const innerStart = before.length + lead.length + 4
+  return { value: next, start: innerStart, end: innerStart + sel.length }
+}
+
+function applyLink(state: TextState): TextState {
+  const { value, start, end } = state
+  const sel = value.slice(start, end)
+  let text: string
+  let selStart: number
+  let selEnd: number
+  if (/^https?:\/\/\S+$/.test(sel)) {
+    text = `[](${sel})`
+    selStart = selEnd = start + 1
+  } else if (sel) {
+    text = `[${sel}](url)`
+    selStart = start + sel.length + 3
+    selEnd = selStart + 3
+  } else {
+    text = '[link text](url)'
+    selStart = start + 1
+    selEnd = selStart + 9
+  }
+  return { value: value.slice(0, start) + text + value.slice(end), start: selStart, end: selEnd }
+}
+
+export function applyFormat(state: TextState, action: FormatAction): TextState {
+  switch (action.kind) {
+    case 'inline':
+      return applyInline(state, action.marker)
+    case 'prefix':
+      return applyPrefix(state, action.prefix)
+    case 'heading':
+      return applyHeading(state, action.level)
+    case 'codeBlock':
+      return applyCodeBlock(state)
+    case 'link':
+      return applyLink(state)
+  }
+}
diff --git a/frontend/src/pages/HelpPage.tsx b/frontend/src/pages/HelpPage.tsx
index c0f1106..1329505 100644
--- a/frontend/src/pages/HelpPage.tsx
+++ b/frontend/src/pages/HelpPage.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'react'
 import Markdown from 'markdown-to-jsx'
-import { Link } from 'react-router-dom'
+import { Link, useLocation } from 'react-router-dom'
 import { createMarkdownOptions, preprocessMarkdown } from '../components/MessageContent'
 import { TopBar } from '../components/TopBar'
 import './HelpPage.css'
@@ -20,6 +20,15 @@ export function HelpPage() {
     [content],
   )
 
+  // #75: the composer's "?" links straight to /help#formatting, but the guide
+  // is fetched after the page loads -- the browser's own scroll-to-hash has
+  // already run (and found nothing) by the time the headings exist.
+  const { hash } = useLocation()
+  useEffect(() => {
+    if (!markdownPreview || !hash) return
+    document.getElementById(hash.slice(1))?.scrollIntoView()
+  }, [markdownPreview, hash])
+
   useEffect(() => {
     let cancelled = false
     fetch(GUIDE_URL)