@gavin-hu/my-pi-agent 0.7.0 → 0.8.1

package/extensions/file-browse/html.ts

@@ -22,7 +22,7 @@ import { formatSize, type DirEntry, type FileView, type Listing, type TreeNode }
 import type { GitStatus } from "./git.ts";
 import { detectLanguage, highlightLines, type HighlightLanguage } from "../../lib/highlight.ts";
 import { FOLDER_ICON, iconHref, languageOf, SPRITE, type IconSpec } from "./icons.ts";
-import { renderMarkdown } from "./markdown.ts";
+import { renderMarkdownDocument, type MarkdownHeading } from "./markdown.ts";
 import { encodePath } from "./paths.ts";
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
@@ -78,6 +78,13 @@ ${WEB_COMPONENTS_CSS}
 .browse-broken{color:var(--muted);text-decoration:line-through}
 .browse-link-mark{color:var(--muted);font-size:var(--fs-xs)}
 .browse-when{display:none}
+.browse-md-outline{max-width:80ch;margin:0 0 var(--space-3) var(--space-4);border:1px solid var(--border);border-radius:var(--radius-md);font-size:var(--fs-sm)}
+.browse-md-outline>summary{padding:var(--space-2) var(--space-3);cursor:pointer;color:var(--muted);font-family:var(--font-mono);font-size:var(--fs-xs)}
+.browse-md-outline ul{list-style:none;margin:0;padding:0 var(--space-3) var(--space-2)}
+.browse-md-outline a{display:block;padding:2px 0}
+.browse-md-outline a.lvl1{padding-left:var(--space-3)}
+.browse-md-outline a.lvl2{padding-left:var(--space-5)}
+.browse-md-outline a.lvl3{padding-left:var(--space-7)}
 body.palette-open{overflow:hidden}
 @media (max-width:520px){
 .bf-toolbar .bf-theme-toggle{margin-left:auto}
@@ -253,6 +260,20 @@ function renderCodeLines(lines: string[], language?: HighlightLanguage): string
 	return rendered.map((html) => `<span class="bf-code__line">${html.length > 0 ? html : " "}</span>`).join("");
 }
 
+/** An "on this page" outline from the headings the Markdown renderer emitted. */
+function renderOutline(headings: MarkdownHeading[]): string {
+	if (headings.length < 4) return "";
+	const base = Math.min(...headings.map((heading) => heading.level));
+	const items = headings
+		.map((heading) => {
+			const depth = Math.min(heading.level - base, 3);
+			const label = heading.text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_~]/g, "");
+			return `<li><a class="lvl${depth}" href="#${heading.id}">${escapeHtml(label)}</a></li>`;
+		})
+		.join("");
+	return `<details class="browse-md-outline"><summary>On this page</summary><ul>${items}</ul></details>`;
+}
+
 /** The card-head controls: Markdown mode, line wrapping, and copy actions. */
 function renderFileActions(page: FilePage): string {
 	const isMarkdown = page.file.kind === "markdown";
@@ -275,7 +296,7 @@ function renderFileActions(page: FilePage): string {
 	}
 	if (page.file.kind === "text" || isMarkdown) {
 		groups.push(
-			`<button type="button" class="bf-btn" data-copy="content" data-href="${escapeHtml(rawHref)}" title="Copy the file contents">copy</button>`,
+			`<button type="button" class="bf-btn" data-copy="content" data-href="${escapeHtml(rawHref)}" title="Copy the file contents">copy contents</button>`,
 		);
 	}
 	groups.push(
@@ -296,10 +317,12 @@ export function renderFilePage(page: FilePage): string {
 	let content: string;
 	let note = "";
 	if (page.file.kind === "text" || page.file.kind === "markdown") {
-		content =
-			page.file.kind === "markdown" && !page.markdownRaw
-				? `<div class="bf-md">${renderMarkdown(page.file.lines.join("\n"), markdownBaseDir(page.rel))}</div>`
-				: `<pre class="bf-code bf-code--numbered"><code>${renderCodeLines(page.file.lines, language)}</code></pre>`;
+		if (page.file.kind === "markdown" && !page.markdownRaw) {
+			const rendered = renderMarkdownDocument(page.file.lines.join("\n"), markdownBaseDir(page.rel));
+			content = `${renderOutline(rendered.headings)}<article class="bf-md">${rendered.html}</article>`;
+		} else {
+			content = `<pre class="bf-code bf-code--numbered"><code>${renderCodeLines(page.file.lines, language)}</code></pre>`;
+		}
 		if (page.file.truncated)
 			note = `<p class="bf-note">Showing the first ${page.file.lines.length} of ${page.file.totalLines} lines.</p>`;
 	} else if (page.file.kind === "image") {

package/extensions/file-browse/markdown.ts

@@ -3,9 +3,10 @@
  *
  * It is deliberately not CommonMark: it covers the block and inline constructs
  * that show up in repository READMEs — headings, paragraphs, fenced code,
- * blockquotes, nested and task lists, tables, code spans, emphasis, links, and
- * images. Everything is escaped and only a known set of tags is emitted; raw
- * HTML in the source is shown as text, never executed.
+ * blockquotes, nested and task lists, tables, code spans, emphasis, inline and
+ * reference links, and images. Named and numeric character references are
+ * decoded as literal text. Everything is escaped and only a known set of tags
+ * is emitted; raw HTML in the source is shown as text, never executed.
  *
  * Relative links become `/view/<path>` and relative images become `/raw/<path>`
  * so they resolve from any page URL. The `/view` and `/raw` routes re-vet the
@@ -13,6 +14,10 @@
  * External images are rendered as links (the page CSP is `img-src 'self' data:`)
  * and non-http(s) schemes such as `javascript:` are dropped.
  *
+ * Headings get a stable anchor id and are demoted one level so the embedding
+ * page keeps the only `h1`; `renderMarkdownDocument` returns them for an
+ * outline.
+ *
  * Kept free of the page renderer: it imports only `lib/escape.ts`,
  * `lib/highlight.ts`, and `paths.ts`, so `html.ts` can compose it without a
  * module cycle.
@@ -26,10 +31,121 @@ import { encodePath } from "./paths.ts";
 const HAS_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
 const SAFE_LINK_SCHEME = /^(?:https?|mailto):/i;
 const HTTP_SCHEME = /^https?:/i;
+/** A link reference definition: `[id]: dest "title"`. */
+const DEFINITION = /^ {0,3}\[([^\]]+)\]:\s*(\S+)(?:\s+["'(]([^"')]*)["')])?\s*$/;
+
+interface LinkDefinition {
+	dest: string;
+	title?: string;
+}
+
+/** A heading the renderer emitted, in document order. */
+export interface MarkdownHeading {
+	/** The rendered tag level, already demoted and capped at `h6`. */
+	level: number;
+	/** The anchor id, unique within the document. */
+	id: string;
+	/** The heading's raw inline Markdown. */
+	text: string;
+}
+
+/**
+ * Per-document render state: the resolution base, the reference definitions,
+ * and the headings emitted so far.
+ */
+interface Context {
+	baseDir: string;
+	defs: Map<string, LinkDefinition>;
+	headings: MarkdownHeading[];
+	slug(text: string): string;
+}
+
+/**
+ * Render a Markdown source string to a safe HTML fragment, plus the headings it
+ * emitted so a caller can build an outline. Headings carry an anchor id and are
+ * demoted one level, so the embedding page keeps the only `h1`.
+ */
+export function renderMarkdownDocument(source: string, baseDir = ""): { html: string; headings: MarkdownHeading[] } {
+	const { defs, body } = collectDefinitions(source.split(/\r\n|\r|\n/));
+	const context = createContext(baseDir, defs);
+	return { html: renderBlocks(body, context), headings: context.headings };
+}
 
 /** Render a Markdown source string to a safe HTML fragment. */
 export function renderMarkdown(source: string, baseDir = ""): string {
-	return renderBlocks(source.split(/\r\n|\r|\n/), baseDir);
+	return renderMarkdownDocument(source, baseDir).html;
+}
+
+/** Turn heading text into a stable anchor id, dropping Markdown punctuation. */
+function headingSlug(text: string): string {
+	const plain = text
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.replace(/[`*_~]/g, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s-]/gu, "")
+		.replace(/[\s-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return plain || "section";
+}
+
+/** Build the per-document render state, suffixing repeated heading slugs. */
+function createContext(baseDir: string, defs: Map<string, LinkDefinition>): Context {
+	const seen = new Map<string, number>();
+	return {
+		baseDir,
+		defs,
+		headings: [],
+		slug(text: string): string {
+			const base = headingSlug(text);
+			const count = seen.get(base) ?? 0;
+			seen.set(base, count + 1);
+			return count === 0 ? base : `${base}-${count}`;
+		},
+	};
+}
+
+/** Fold a reference label the way CommonMark does: trim, collapse, case-fold. */
+function normalizeLabel(label: string): string {
+	return label.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/**
+ * Lift link reference definitions out of the source before block rendering, so
+ * a `[id]: dest` line becomes a definition rather than a paragraph and can be
+ * referenced from anywhere in the document. Fences are skipped so a
+ * definition-shaped line inside code stays literal. Definitions are
+ * single-line; one inside a blockquote or list item is left in place as text.
+ */
+function collectDefinitions(lines: string[]): { defs: Map<string, LinkDefinition>; body: string[] } {
+	const defs = new Map<string, LinkDefinition>();
+	const body: string[] = [];
+	let fence: Fence | undefined;
+	for (const line of lines) {
+		if (fence) {
+			const close = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line);
+			if (close && close[1][0] === fence.char && close[1].length >= fence.length) fence = undefined;
+			body.push(line);
+			continue;
+		}
+		const open = matchFence(line);
+		if (open) {
+			fence = open;
+			body.push(line);
+			continue;
+		}
+		const match = DEFINITION.exec(line);
+		if (!match) {
+			body.push(line);
+			continue;
+		}
+		const key = normalizeLabel(match[1]);
+		if (!defs.has(key)) {
+			const dest = match[2].startsWith("<") && match[2].endsWith(">") ? match[2].slice(1, -1) : match[2];
+			defs.set(key, { dest, title: match[3] });
+		}
+		body.push("");
+	}
+	return { defs, body };
 }
 
 function isBlank(line: string): boolean {
@@ -56,7 +172,7 @@ function stripIndent(line: string, columns: number): string {
 	return line.slice(index);
 }
 
-function renderBlocks(lines: string[], baseDir: string): string {
+function renderBlocks(lines: string[], ctx: Context): string {
 	const out: string[] = [];
 	let i = 0;
 	while (i < lines.length) {
@@ -76,7 +192,10 @@ function renderBlocks(lines: string[], baseDir: string): string {
 
 		const heading = matchHeading(line);
 		if (heading) {
-			out.push(`<h${heading.level}>${renderInline(heading.text, baseDir)}</h${heading.level}>`);
+			const level = Math.min(heading.level + 1, 6);
+			const id = ctx.slug(heading.text);
+			ctx.headings.push({ level, id, text: heading.text });
+			out.push(`<h${level} id="${id}">${renderInline(heading.text, ctx)}</h${level}>`);
 			i++;
 			continue;
 		}
@@ -88,27 +207,29 @@ function renderBlocks(lines: string[], baseDir: string): string {
 		}
 
 		if (isBlockquoteLine(line)) {
-			const [html, next] = renderBlockquote(lines, i, baseDir);
+			const [html, next] = renderBlockquote(lines, i, ctx);
 			out.push(html);
 			i = next;
 			continue;
 		}
 
-		if (i + 1 < lines.length && isTableStart(line, lines[i + 1])) {
-			const [html, next] = renderTable(lines, i, baseDir);
+		// A list marker wins over a pipe, so `- | a | b |` stays a list item
+		// instead of becoming a table whose first cell is `-`.
+		if (matchListItem(line)) {
+			const [html, next] = renderList(lines, i, ctx);
 			out.push(html);
 			i = next;
 			continue;
 		}
 
-		if (matchListItem(line)) {
-			const [html, next] = renderList(lines, i, baseDir);
+		if (i + 1 < lines.length && isTableStart(line, lines[i + 1])) {
+			const [html, next] = renderTable(lines, i, ctx);
 			out.push(html);
 			i = next;
 			continue;
 		}
 
-		const [html, next] = renderParagraph(lines, i, baseDir);
+		const [html, next] = renderParagraph(lines, i, ctx);
 		out.push(html);
 		i = next;
 	}
@@ -128,7 +249,7 @@ function isBlockStart(lines: string[], i: number): boolean {
 	);
 }
 
-function renderParagraph(lines: string[], start: number, baseDir: string): [string, number] {
+function renderParagraph(lines: string[], start: number, ctx: Context): [string, number] {
 	const collected: string[] = [];
 	let i = start;
 	for (; i < lines.length; i++) {
@@ -141,7 +262,7 @@ function renderParagraph(lines: string[], start: number, baseDir: string): [stri
 			let text = line.trimEnd();
 			const hard = / {2}$/.test(line) || /\\$/.test(text);
 			if (text.endsWith("\\")) text = text.slice(0, -1);
-			const rendered = renderInline(text.trim(), baseDir);
+			const rendered = renderInline(text.trim(), ctx);
 			return hard ? `${rendered}<br>` : rendered;
 		})
 		.join("\n");
@@ -192,7 +313,7 @@ function isBlockquoteLine(line: string): boolean {
 	return /^ {0,3}>/.test(line);
 }
 
-function renderBlockquote(lines: string[], start: number, baseDir: string): [string, number] {
+function renderBlockquote(lines: string[], start: number, ctx: Context): [string, number] {
 	const inner: string[] = [];
 	let i = start;
 	for (; i < lines.length; i++) {
@@ -207,7 +328,7 @@ function renderBlockquote(lines: string[], start: number, baseDir: string): [str
 		}
 		break;
 	}
-	return [`<blockquote>${renderBlocks(inner, baseDir)}</blockquote>`, i];
+	return [`<blockquote>${renderBlocks(inner, ctx)}</blockquote>`, i];
 }
 
 function splitTableRow(line: string): string[] {
@@ -237,7 +358,10 @@ function splitTableRow(line: string): string[] {
 function isTableStart(header: string, delimiter: string): boolean {
 	if (!header.includes("|")) return false;
 	const cells = splitTableRow(delimiter);
-	return cells.length > 0 && cells.every((cell) => /^:?-+:?$/.test(cell));
+	// GFM requires the delimiter row to match the header row's cell count;
+	// otherwise the lines are a paragraph, not a table.
+	if (cells.length === 0 || cells.length !== splitTableRow(header).length) return false;
+	return cells.every((cell) => /^:?-+:?$/.test(cell));
 }
 
 function alignmentClass(cell: string): string {
@@ -249,10 +373,12 @@ function alignmentClass(cell: string): string {
 	return "";
 }
 
-function renderTable(lines: string[], start: number, baseDir: string): [string, number] {
+function renderTable(lines: string[], start: number, ctx: Context): [string, number] {
 	const header = splitTableRow(lines[start]);
 	const align = splitTableRow(lines[start + 1]).map(alignmentClass);
-	const head = header.map((cell, index) => `<th${align[index] ?? ""}>${renderInline(cell, baseDir)}</th>`).join("");
+	const head = header
+		.map((cell, index) => `<th scope="col"${align[index] ?? ""}>${renderInline(cell, ctx)}</th>`)
+		.join("");
 	const rows: string[] = [];
 	let i = start + 2;
 	for (; i < lines.length; i++) {
@@ -260,11 +386,12 @@ function renderTable(lines: string[], start: number, baseDir: string): [string,
 		const cells = splitTableRow(lines[i]);
 		const tds: string[] = [];
 		for (let column = 0; column < header.length; column++) {
-			tds.push(`<td${align[column] ?? ""}>${renderInline(cells[column] ?? "", baseDir)}</td>`);
+			tds.push(`<td${align[column] ?? ""}>${renderInline(cells[column] ?? "", ctx)}</td>`);
 		}
 		rows.push(`<tr>${tds.join("")}</tr>`);
 	}
-	return [`<table class="md-table"><thead><tr>${head}</tr></thead><tbody>${rows.join("")}</tbody></table>`, i];
+	const table = `<table class="md-table"><thead><tr>${head}</tr></thead><tbody>${rows.join("")}</tbody></table>`;
+	return [`<div class="md-table-wrap">${table}</div>`, i];
 }
 
 interface ListItem {
@@ -285,9 +412,9 @@ function matchListItem(line: string): ListItem | undefined {
 	};
 }
 
-function renderList(lines: string[], start: number, baseDir: string): [string, number] {
+function renderList(lines: string[], start: number, ctx: Context): [string, number] {
 	const first = matchListItem(lines[start]);
-	if (!first) return renderParagraph(lines, start, baseDir);
+	if (!first) return renderParagraph(lines, start, ctx);
 	const baseIndent = first.indent;
 	const ordered = first.ordered;
 	const items: string[] = [];
@@ -323,20 +450,20 @@ function renderList(lines: string[], start: number, baseDir: string): [string, n
 			}
 			break;
 		}
-		items.push(renderListItem(contentLines, baseDir));
+		items.push(renderListItem(contentLines, ctx));
 	}
 	const tag = ordered ? "ol" : "ul";
 	return [`<${tag}>${items.join("")}</${tag}>`, i];
 }
 
-function renderListItem(contentLines: string[], baseDir: string): string {
+function renderListItem(contentLines: string[], ctx: Context): string {
 	const task = /^\[([ xX])\]\s*(.*)$/.exec(contentLines[0] ?? "");
 	const done = task ? task[1].toLowerCase() === "x" : false;
 	const source = task ? [task[2], ...contentLines.slice(1)] : contentLines;
 	const tight = !source.some(isBlank);
-	let body = renderBlocks(source, baseDir);
+	let body = renderBlocks(source, ctx);
 	if (tight) body = body.replace(/<\/?p>/g, "");
-	const mark = task ? `<span class="md-check" aria-hidden="true">${done ? "☑" : "☐"}</span> ` : "";
+	const mark = task ? `<input class="md-check" type="checkbox" disabled${done ? " checked" : ""}> ` : "";
 	return `<li${task ? (done ? ` class="task done"` : ` class="task"`) : ""}>${mark}${body}</li>`;
 }
 
@@ -347,11 +474,10 @@ interface ParsedLink {
 	end: number;
 }
 
-function parseInlineLink(text: string, start: number): ParsedLink | undefined {
-	if (text[start] !== "[") return undefined;
+/** The index of the `]` closing the bracket run opened at `start`, or -1. */
+function matchBracket(text: string, start: number): number {
 	let depth = 0;
-	let i = start;
-	for (; i < text.length; i++) {
+	for (let i = start; i < text.length; i++) {
 		const char = text[i];
 		if (char === "\\") {
 			i++;
@@ -360,10 +486,16 @@ function parseInlineLink(text: string, start: number): ParsedLink | undefined {
 		if (char === "[") depth++;
 		else if (char === "]") {
 			depth--;
-			if (depth === 0) break;
+			if (depth === 0) return i;
 		}
 	}
-	if (i >= text.length || text[i] !== "]" || text[i + 1] !== "(") return undefined;
+	return -1;
+}
+
+function parseInlineLink(text: string, start: number): ParsedLink | undefined {
+	if (text[start] !== "[") return undefined;
+	const i = matchBracket(text, start);
+	if (i === -1 || text[i + 1] !== "(") return undefined;
 	const label = text.slice(start + 1, i);
 	let j = i + 2;
 	while (j < text.length && /\s/.test(text[j])) j++;
@@ -409,6 +541,29 @@ function parseInlineLink(text: string, start: number): ParsedLink | undefined {
 	return { label, dest, title, end: j + 1 };
 }
 
+/**
+ * Resolve `[label][id]`, `[label][]`, or `[label]` against the document's
+ * reference definitions, preferring the full form and falling back to the
+ * shortcut so `[foo][bar]` still resolves `[foo]` when only that is defined.
+ */
+function parseReferenceLink(text: string, start: number, ctx: Context): ParsedLink | undefined {
+	if (text[start] !== "[") return undefined;
+	const close = matchBracket(text, start);
+	if (close === -1 || text[close + 1] === "(") return undefined;
+	const label = text.slice(start + 1, close);
+	if (text[close + 1] === "[") {
+		const end = matchBracket(text, close + 1);
+		if (end !== -1) {
+			const raw = text.slice(close + 2, end);
+			const def = ctx.defs.get(normalizeLabel(raw === "" ? label : raw));
+			if (def) return { label, dest: def.dest, title: def.title, end: end + 1 };
+		}
+	}
+	const def = ctx.defs.get(normalizeLabel(label));
+	if (def) return { label, dest: def.dest, title: def.title, end: close + 1 };
+	return undefined;
+}
+
 interface ResolvedLink {
 	href: string;
 	external: boolean;
@@ -459,18 +614,18 @@ function resolveImage(dest: string, baseDir: string): ResolvedImage | undefined
 	return { href: `/raw/${encodePath(local.rel)}${local.suffix}`, image: true };
 }
 
-function renderLink(parsed: ParsedLink, baseDir: string): string {
-	const label = renderInline(parsed.label, baseDir);
-	const target = resolveLink(parsed.dest, baseDir);
+function renderLink(parsed: ParsedLink, ctx: Context): string {
+	const label = renderInline(parsed.label, ctx);
+	const target = resolveLink(parsed.dest, ctx.baseDir);
 	if (!target) return label;
 	const title = parsed.title ? ` title="${escapeHtml(parsed.title)}"` : "";
 	const external = target.external ? ` target="_blank" rel="noopener noreferrer"` : "";
 	return `<a href="${escapeHtml(target.href)}"${title}${external}>${label}</a>`;
 }
 
-function renderImage(parsed: ParsedLink, baseDir: string): string {
+function renderImage(parsed: ParsedLink, ctx: Context): string {
 	const alt = escapeHtml(parsed.label);
-	const target = resolveImage(parsed.dest, baseDir);
+	const target = resolveImage(parsed.dest, ctx.baseDir);
 	if (!target) return alt;
 	if (!target.image) {
 		return `<a href="${escapeHtml(target.href)}" target="_blank" rel="noopener noreferrer">${alt || escapeHtml(parsed.dest)}</a>`;
@@ -504,8 +659,86 @@ function findEmphasisClose(text: string, start: number, char: string): number {
 	return -1;
 }
 
+/**
+ * The named character references common enough to matter in a README. Anything
+ * outside this set stays literal; numeric references are always decoded.
+ */
+const NAMED_ENTITIES: Record<string, string> = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: '"',
+	apos: "'",
+	nbsp: "\u00a0",
+	copy: "©",
+	reg: "®",
+	trade: "™",
+	hellip: "…",
+	mdash: "—",
+	ndash: "–",
+	lsquo: "‘",
+	rsquo: "’",
+	ldquo: "“",
+	rdquo: "”",
+	laquo: "«",
+	raquo: "»",
+	times: "×",
+	divide: "÷",
+	middot: "·",
+	bull: "•",
+	deg: "°",
+	plusmn: "±",
+	dagger: "†",
+	sect: "§",
+	para: "¶",
+	euro: "€",
+	pound: "£",
+	yen: "¥",
+	cent: "¢",
+	larr: "←",
+	rarr: "→",
+	harr: "↔",
+	le: "≤",
+	ge: "≥",
+	ne: "≠",
+	asymp: "≈",
+	sup2: "²",
+	sup3: "³",
+	frac12: "½",
+	frac14: "¼",
+	frac34: "¾",
+};
+
+interface Entity {
+	value: string;
+	length: number;
+}
+
+/** A code point, or U+FFFD when the reference is a surrogate or out of range. */
+function codePoint(value: number): string {
+	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
+		return "\uFFFD";
+	return String.fromCodePoint(value);
+}
+
+/**
+ * Match a numeric or named character reference at `start`. Decoding happens in
+ * the inline scanner rather than a pre-pass so an entity cannot become Markdown
+ * syntax: `&#42;x&#42;` stays the literal text `*x*`.
+ */
+function matchEntity(text: string, start: number): Entity | undefined {
+	const match = /^&(?:#([0-9]{1,7})|#[xX]([0-9a-fA-F]{1,6})|([a-zA-Z][a-zA-Z0-9]{1,31}));/.exec(text.slice(start));
+	if (!match) return undefined;
+	let value: string | undefined;
+	if (match[1] !== undefined) value = codePoint(Number(match[1]));
+	else if (match[2] !== undefined) value = codePoint(Number.parseInt(match[2], 16));
+	else if (match[3] !== undefined && Object.hasOwn(NAMED_ENTITIES, match[3])) value = NAMED_ENTITIES[match[3]];
+	if (value === undefined) return undefined;
+	return { value, length: match[0].length };
+}
+
 /** Render inline Markdown within a block, escaping every literal character. */
-function renderInline(text: string, baseDir: string): string {
+function renderInline(text: string, ctx: Context): string {
 	let out = "";
 	let i = 0;
 	while (i < text.length) {
@@ -517,6 +750,15 @@ function renderInline(text: string, baseDir: string): string {
 			continue;
 		}
 
+		if (char === "&") {
+			const entity = matchEntity(text, i);
+			if (entity) {
+				out += escapeHtml(entity.value);
+				i += entity.length;
+				continue;
+			}
+		}
+
 		if (char === "`") {
 			const run = matchRun(text, i, "`");
 			const close = text.indexOf("`".repeat(run), i + run);
@@ -530,18 +772,18 @@ function renderInline(text: string, baseDir: string): string {
 		}
 
 		if (char === "!" && text[i + 1] === "[") {
-			const parsed = parseInlineLink(text, i + 1);
+			const parsed = parseInlineLink(text, i + 1) ?? parseReferenceLink(text, i + 1, ctx);
 			if (parsed) {
-				out += renderImage(parsed, baseDir);
+				out += renderImage(parsed, ctx);
 				i = parsed.end;
 				continue;
 			}
 		}
 
 		if (char === "[") {
-			const parsed = parseInlineLink(text, i);
+			const parsed = parseInlineLink(text, i) ?? parseReferenceLink(text, i, ctx);
 			if (parsed) {
-				out += renderLink(parsed, baseDir);
+				out += renderLink(parsed, ctx);
 				i = parsed.end;
 				continue;
 			}
@@ -561,7 +803,7 @@ function renderInline(text: string, baseDir: string): string {
 		if ((char === "*" || char === "_") && text[i + 1] === char) {
 			const close = text.indexOf(char + char, i + 2);
 			if (close > i + 2) {
-				out += `<strong>${renderInline(text.slice(i + 2, close), baseDir)}</strong>`;
+				out += `<strong>${renderInline(text.slice(i + 2, close), ctx)}</strong>`;
 				i = close + 2;
 				continue;
 			}
@@ -570,7 +812,7 @@ function renderInline(text: string, baseDir: string): string {
 		if (char === "~" && text[i + 1] === "~") {
 			const close = text.indexOf("~~", i + 2);
 			if (close > i + 2) {
-				out += `<del>${renderInline(text.slice(i + 2, close), baseDir)}</del>`;
+				out += `<del>${renderInline(text.slice(i + 2, close), ctx)}</del>`;
 				i = close + 2;
 				continue;
 			}
@@ -579,7 +821,7 @@ function renderInline(text: string, baseDir: string): string {
 		if (char === "*" || char === "_") {
 			const close = findEmphasisClose(text, i, char);
 			if (close > i + 1) {
-				out += `<em>${renderInline(text.slice(i + 1, close), baseDir)}</em>`;
+				out += `<em>${renderInline(text.slice(i + 1, close), ctx)}</em>`;
 				i = close + 1;
 				continue;
 			}