@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karim Alibhai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+<p align="center">
+    <img src="client/favicon.svg" alt="mdxserve logo" width="96" height="96" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">mdxserve</h1>
+
+<p align="center">The prettiest way to view Markdown and MDX.</p>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/@karimsa/mdxserve">
+        <img src="https://img.shields.io/npm/v/@karimsa/mdxserve" alt="npm version" />
+    </a>
+    <a href="LICENSE">
+        <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
+    </a>
+</p>
+
+Point it at a folder of `.md` / `.mdx` files and it serves them as a site you can browse: a
+listing of every folder, each file rendered as a page with syntax-highlighted code, mermaid
+diagrams, and a set of builtin components, in light and dark. Save a file and the open page
+updates. Write JSX in an `.mdx` file and it renders too.
+
+![A rendered Markdown page in the light theme: sidebar file tree, prose column, table of contents](docs/screenshots/reader-light.jpg)
+
+![The same page in the dark theme](docs/screenshots/reader-dark.jpg)
+
+It is built for folders of Markdown that already exist — notes, a `docs/` directory, plan
+files an AI agent wrote — rather than for publishing a site. There is no build step and no
+config file: run it, open the URL, read.
+
+## Install
+
+You need Node 22.12 or newer.
+
+```bash
+npm install -g @karimsa/mdxserve
+mdxserve setup      # optional: installs the writing skill for Claude Code and Codex
+```
+
+`mdxserve setup` copies the agent writing skill into your Claude Code and Codex skill folders
+(through `npx skills add`) and removes the MCP registration that older versions created. It is
+safe to re-run; run it again after upgrading so the installed skill matches the CLI.
+
+## Quick start
+
+```bash
+mdxserve serve -w ~/notes          # serve one folder
+mdxserve serve -w ~/notes -w ~/work/docs   # or several unrelated folders at once
+```
+
+Open the URL it prints (`http://127.0.0.1:4040` by default). With one folder you land in its
+listing; with several, the home page lists them.
+
+One server runs per user, and you can change what it serves without restarting it:
+
+```bash
+mdxserve roots add ~/work/docs     # start serving another folder
+mdxserve roots remove ~/notes      # stop serving one
+mdxserve roots list                # what is being served right now
+mdxserve status                    # pid, port, URL, and the folders served
+```
+
+Folders you add this way last until the server stops. `mdxserve serve` with no `-w` starts
+an empty server you can add folders to later.
+
+| Flag          | Default     | Effect                                                    |
+| ------------- | ----------- | --------------------------------------------------------- |
+| `-w, --watch` | none        | Serve this folder; repeat the flag for more than one      |
+| `-p, --port`  | `4040`      | Port to listen on; falls back to a free one if it's taken |
+| `--host`      | `127.0.0.1` | Interface to bind; `0.0.0.0` exposes it on your LAN       |
+
+## Writing docs
+
+Any folder of Markdown works as-is. `.md` and `.mdx` are treated identically: both get
+GitHub-flavored Markdown (tables, task lists, strikethrough), syntax-highlighted code blocks,
+and mermaid diagrams. In an `.mdx` file you can also use JSX, `export` values, and `import`
+your own React components.
+
+Code fences take a title, a line-number gutter, and highlighted lines on the opening line:
+
+````md
+```ts title="src/server.ts" showLineNumbers {3-4}
+const server = http.createServer(handler);
+server.listen(port);
+// these two lines are highlighted
+console.log(`http://localhost:${port}`);
+```
+````
+
+A ` ```mermaid ` fence renders as a pan-and-zoom diagram with a Diagram / Code toggle:
+
+````md
+```mermaid
+flowchart LR
+  Browser -->|GET /notes/intro.md| Server
+  Server -->|compile via Vite| Page[Rendered page]
+```
+````
+
+![Mermaid diagrams rendered in the dark theme](docs/screenshots/diagrams-dark.jpg)
+
+### Builtin components
+
+A small set of components is available in every file, `.md` included, with no import:
+
+| Component           | For                                                      |
+| ------------------- | -------------------------------------------------------- |
+| `Callout`           | A note, tip, or warning the reader must not miss         |
+| `Tabs` / `Tab`      | Per-OS or per-language variants of the same instructions |
+| `Badge`             | A status or tag inline with text                         |
+| `Tooltip`           | A short explanation on hover                             |
+| `Button`            | A link styled as a call to action                        |
+| `Diff`              | A before/after code change, unified or side by side      |
+| `Card` / `CardGrid` | Linked cards laid out in a grid                          |
+| `Kbd`               | A keyboard shortcut                                      |
+| `FileTree`          | The shape of a directory                                 |
+| `Chart`             | A bar (vertical or horizontal), line, area, or histogram |
+| `Sparkline`         | A tiny inline trend line                                 |
+| `Dropdown`          | A picker, or a switcher between longer panels of content |
+| `Screenshot`        | An app or UI screenshot framed as a macOS window         |
+
+```mdx
+<Callout tone="warn" title="Before you deploy">
+	Rotate the key first; the old one stops working immediately.
+</Callout>
+
+<Tabs>
+	<Tab label="macOS">`brew install foo`</Tab>
+	<Tab label="Linux">`apt install foo`</Tab>
+</Tabs>
+
+Status: <Badge tone="ok" dot>Online</Badge>
+```
+
+![Chart, Sparkline and Dropdown builtins in the light theme](docs/screenshots/builtins-light.jpg)
+
+Every component's props are documented from the command line:
+
+```bash
+mdxserve components search           # list them all
+mdxserve components show Callout     # props, defaults, and when to use it
+```
+
+### Your own components
+
+An `.mdx` file can `import` a `.tsx` / `.jsx` component from next to it and use it as JSX.
+Imports resolve relative to the file, like any other Vite import, and Tailwind utility classes
+work anywhere. A local import with the same name as a builtin wins.
+
+```mdx
+import { Counter } from "./components/Counter";
+
+<Counter start={3} />
+```
+
+### The example folder
+
+[`example/`](./example) is a working tour of everything above — plain Markdown, MDX, custom
+components, Tailwind, every builtin, and a page of charts. From a clone, after `yarn`:
+
+```bash
+yarn dev    # serves ./example
+```
+
+## Reading and editing
+
+Every page has the same shell: a sidebar listing the folder you are in, the document, and a
+table of contents that follows you as you scroll. The sidebar and the content column are
+resizable. Pages link to their previous and next neighbour and show which file they came from
+and when it was last edited.
+
+- `⌘K` / `Ctrl K` searches every served folder by title, heading, and body.
+- The top bar toggles light and dark (it remembers your choice), prints, and exports.
+- Double-click a section, or use its pencil, to edit it in place; `⌘S` saves,
+  `Esc` cancels. The edit is written back to the file on disk.
+- Saving a file from your editor re-renders the open page, and a toast names what changed.
+- In a folder listing, select files to move them to the OS Trash (never deleted outright).
+- Diagrams and charts open full-screen; a flowchart's direction can be flipped without
+  touching the source.
+
+Navigation is client-side — moving between folders and pages doesn't reload — and every
+animation respects `prefers-reduced-motion`.
+
+## Exporting a page
+
+`mdxserve export` turns one document into a single HTML file that opens from `file://` on any
+machine, with the same theme, code blocks, diagrams, and components as the live viewer:
+
+```bash
+mdxserve export docs/guide.md                     # writes ./guide.html
+mdxserve export docs/guide.md -o ~/Desktop/guide.html
+mdxserve export docs/guide.md --mermaid bundle    # fully offline; inlines mermaid (~2.4 MB)
+```
+
+The same export is in the viewer's top bar on any page. See
+[`docs/advanced.md`](./docs/advanced.md#exporting) for exactly what the file does and doesn't
+carry.
+
+## Using it with AI agents
+
+mdxserve is a good place to read what an agent writes — plan files, reports, design docs —
+and it gives the agent tools to write for it well:
+
+- **A writing skill.** `skills/mdxserve/SKILL.md` teaches an agent to write Markdown that
+  renders richly here while staying plain and portable, and to check the builtin components
+  before using them. `mdxserve setup` installs it for Claude Code and Codex.
+- **CLI verbs.** `mdxserve validate`, `search`, `docs`, `roots`, and `components` all take
+  `--json`, so an agent can check a file, find docs, and manage served folders from a shell.
+
+`validate` works without a server (compile errors, unknown components and props) but only
+renders the doc when an `mdxserve serve` is running.
+[`docs/advanced.md`](./docs/advanced.md#the-agent-cli) covers the verbs in detail.
+
+## Keeping it running
+
+`mdxserve serve` runs in the foreground. To keep it up after you close the terminal, use any
+process manager — [oxmgr](https://github.com/Vladimir-Urik/OxMgr) is one option:
+
+```bash
+oxmgr start "mdxserve serve"
+mdxserve roots add ~/notes
+
+oxmgr logs mdxserve      # tail the server log
+oxmgr stop mdxserve      # stop it
+```
+
+## Going further
+
+| Read                                           | If you want to                                                                                                             |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| [`docs/advanced.md`](./docs/advanced.md)       | Understand the one-server-per-user model, URL and root rules, LAN exposure, the cache, exports in depth, and the agent CLI |
+| [`docs/http-api.md`](./docs/http-api.md)       | Call the server's typed HTTP API directly                                                                                  |
+| [`docs/development.md`](./docs/development.md) | Work on mdxserve itself: build, test, add a builtin, and where things live                                                 |
+| [`AGENTS.md`](./AGENTS.md)                     | The architecture rules the codebase follows (also what coding agents read)                                                 |

package/client/App.tsx

@@ -0,0 +1,7 @@
+import { AppShell } from "./shell/AppShell";
+import { useRouter, type Route } from "./router";
+
+export function App({ initialRoute }: { initialRoute: Route }) {
+	const { route, navigate } = useRouter(initialRoute);
+	return <AppShell route={route} navigate={navigate} />;
+}

package/client/CodeBlock.tsx

@@ -0,0 +1,395 @@
+import {
+	Children,
+	createContext,
+	isValidElement,
+	useContext,
+	useEffect,
+	useId,
+	useRef,
+	useState,
+	type ComponentPropsWithoutRef,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import { MermaidDiagram } from "./Mermaid";
+import {
+	readFlowchartDirection,
+	setFlowchartDirection,
+	type FlowDirection,
+} from "./mermaid-direction";
+import { useMediaQuery } from "./hooks";
+import { DESKTOP_MEDIA } from "./platform";
+import Dropdown from "./builtins/Dropdown";
+import { TRANSITIONS } from "./motion";
+import { CrossFade } from "./CrossFade";
+import { Icon } from "./ui/Icon";
+
+/**
+ * Code block chrome for MDX-compiled output, styled from the design tokens
+ * (bg-code-bg / border-code-border / text-code-fg — see client/design/tokens/colors.css).
+ *
+ * rehype-pretty-code (node_modules/rehype-pretty-code/dist/index.js) wraps every fenced
+ * code block as:
+ *
+ *   <figure data-rehype-pretty-code-figure>                                  // index.js:459
+ *     <figcaption data-rehype-pretty-code-title                              // index.js:506-510
+ *                  data-language data-theme>title</figcaption>               // only when `title="…"` meta is set
+ *     <pre data-language data-theme>                                        // index.js:478-479
+ *       <code data-language data-theme style="display:grid"                 // index.js:483-484, 495-498
+ *             data-line-numbers?                                            // index.js:748, set on <code> when `showLineNumbers` meta present
+ *             data-line-numbers-max-digits?>                                // index.js:499-500
+ *         <span data-line data-highlighted-line?>…</span>                   // index.js:459(line loop)/766, "line" class -> data-line, {n,m-n} meta -> data-highlighted-line
+ *       </code>
+ *     </pre>
+ *   </figure>
+ *
+ * We intercept both `figure` and `pre` in the MDXProvider components map (see
+ * client/entry.tsx). `Figure` renders the framed card (header bar + copy button)
+ * for processed code figures, pulling the title out of the figcaption and the
+ * language off the `pre`; `Pre` then renders as a bare, styled `<pre>` inside
+ * that card. A `<pre>` that is *not* inside one of our `Figure`s (e.g.
+ * hand-written JSX in an .mdx file, which bypasses rehype-pretty-code entirely)
+ * falls back to rendering the same card itself, so plain `<pre>` still looks right.
+ * `CodeFrame` is the single source of truth for that card, used by both paths;
+ * `CodeFrameHeader` is its header bar, exported standalone so other framed
+ * code-like surfaces (e.g. the Diff builtin) can reuse the same chrome.
+ */
+
+const InsideCodeFrame = createContext(false);
+
+/**
+ * The 34px header bar shared by every code-shaped frame: a mono filename/
+ * language label on the left, arbitrary actions (copy button, view toggle) on
+ * the right.
+ */
+export function CodeFrameHeader({ label, actions }: { label?: ReactNode; actions?: ReactNode }) {
+	return (
+		<div className="flex h-[38px] items-center gap-3 border-b border-code-border pr-2.5 pl-4">
+			<span className="min-w-0 flex-1 truncate font-mono text-[length:var(--size-xs)] text-text-subtle">
+				{label}
+			</span>
+			{/* Each action is its own group; a hairline keeps a segmented control and
+          the copy button from reading as one cluster. */}
+			{actions ? (
+				<div className="flex items-center gap-3 [&>*+*]:border-l [&>*+*]:border-code-border [&>*+*]:pl-3">
+					{actions}
+				</div>
+			) : null}
+		</div>
+	);
+}
+
+/** Copy-to-clipboard button with a crossfading copy/check icon and label. */
+function CopyButton({ getText }: { getText: () => string }) {
+	const [copied, setCopied] = useState(false);
+
+	async function handleCopy() {
+		const text = getText();
+		if (!text) return;
+		try {
+			await navigator.clipboard.writeText(text);
+			setCopied(true);
+			setTimeout(() => setCopied(false), 1500);
+		} catch {
+			// clipboard unavailable; ignore
+		}
+	}
+
+	return (
+		<motion.button
+			type="button"
+			onClick={handleCopy}
+			layout
+			whileTap={{ scale: 0.94 }}
+			transition={TRANSITIONS.snap}
+			className={
+				"inline-flex h-6 cursor-pointer items-center gap-1.5 rounded-sm px-2 font-sans text-[length:var(--size-xs)] font-medium leading-none transition-colors " +
+				(copied ? "text-text-accent" : "text-text-subtle hover:text-text-heading")
+			}
+		>
+			<AnimatePresence mode="wait" initial={false}>
+				<motion.span
+					key={copied ? "done" : "idle"}
+					initial={{ opacity: 0, y: -3 }}
+					animate={{ opacity: 1, y: 0 }}
+					exit={{ opacity: 0, y: 3 }}
+					transition={TRANSITIONS.fast}
+					className="inline-flex items-center gap-1.5"
+				>
+					<Icon name={copied ? "check" : "copy"} size={13} />
+					{copied ? "Copied" : "Copy"}
+				</motion.span>
+			</AnimatePresence>
+		</motion.button>
+	);
+}
+
+const DIRECTION_ICON: Record<FlowDirection, string> = {
+	TB: "arrow-down",
+	BT: "arrow-up",
+	LR: "arrow-right",
+	RL: "arrow-left",
+};
+
+const DIRECTION_LABEL: Record<FlowDirection, string> = {
+	TB: "Top to bottom",
+	BT: "Bottom to top",
+	LR: "Left to right",
+	RL: "Right to left",
+};
+
+/**
+ * Picks how a flowchart is laid out for the reader's view only: the source
+ * on disk, the code pane and the copy button all keep the author's direction.
+ * An icon-only trigger showing the current direction, opening the same menu
+ * the sidebar uses for sorting; the author's own direction is marked so the
+ * reader can always find the way back.
+ */
+function DirectionMenu({
+	value,
+	authored,
+	onChange,
+}: {
+	value: FlowDirection;
+	/** The direction written in the source. */
+	authored: FlowDirection;
+	onChange: (direction: FlowDirection) => void;
+}) {
+	return (
+		<Dropdown
+			icon={DIRECTION_ICON[value]}
+			size="sm"
+			label="Layout"
+			value={value}
+			onChange={(next) => onChange(next as FlowDirection)}
+			options={(Object.keys(DIRECTION_LABEL) as FlowDirection[]).map((direction) => ({
+				value: direction,
+				label: DIRECTION_LABEL[direction],
+				description: direction === authored ? "As written" : undefined,
+			}))}
+		/>
+	);
+}
+
+/** Diagram/Code segmented pill for mermaid frames; the active pill slides via `layoutId`. */
+function ViewToggle({
+	view,
+	onChange,
+	toggleId,
+}: {
+	view: "diagram" | "code";
+	onChange: (view: "diagram" | "code") => void;
+	toggleId: string;
+}) {
+	return (
+		<div
+			role="tablist"
+			className="inline-flex gap-1 rounded-md border border-border-default bg-surface-sunken p-[3px]"
+		>
+			{(
+				[
+					{ value: "diagram", icon: "image" },
+					{ value: "code", icon: "code" },
+				] as const
+			).map((option) => (
+				<button
+					key={option.value}
+					type="button"
+					role="tab"
+					aria-selected={view === option.value}
+					onClick={() => onChange(option.value)}
+					className={
+						"relative inline-flex h-6 cursor-pointer items-center gap-1.5 rounded-sm px-2.5 font-sans text-[length:var(--size-xs)] leading-none capitalize transition-colors " +
+						(view === option.value
+							? "font-semibold text-text-heading"
+							: "font-medium text-text-subtle hover:text-text-heading")
+					}
+				>
+					{view === option.value ? (
+						<motion.span
+							layoutId={`${toggleId}-pill`}
+							transition={TRANSITIONS.snap}
+							className="absolute inset-0 rounded-sm border border-border-default bg-surface-card shadow-xs"
+						/>
+					) : null}
+					<span className="relative z-10 inline-flex items-center gap-1.5">
+						<Icon name={option.icon} size={12} />
+						{option.value}
+					</span>
+				</button>
+			))}
+		</div>
+	);
+}
+
+/**
+ * Shared card: header bar (label + actions) wrapping whatever `<pre>` is
+ * passed as children. Copies via a ref instead of prop-drilling so it works
+ * whether the `<pre>` came from `Figure` or was rendered directly by `Pre`.
+ * Content rises with the rest of the prose column, so the frame itself has no
+ * entrance animation of its own.
+ */
+function CodeFrame({
+	title,
+	language,
+	children,
+}: {
+	title?: string;
+	language?: string;
+	children: ReactNode;
+}) {
+	const containerRef = useRef<HTMLDivElement>(null);
+	const isMermaid = language === "mermaid";
+	const [view, setView] = useState<"diagram" | "code">("diagram");
+	const [source, setSource] = useState<string | null>(null);
+	const label = title ?? language;
+	const showDiagram = isMermaid && view === "diagram";
+	const toggleId = useId();
+
+	// A flow-direction choice is a view setting, not an edit: it is applied to
+	// the text handed to mermaid and nowhere else. Remembering which source it
+	// was chosen for means a re-render with new content (the file was saved with
+	// a different header) falls back to the default automatically.
+	const wideScreen = useMediaQuery(DESKTOP_MEDIA, true);
+	const authored = source === null ? null : readFlowchartDirection(source);
+	// A left-to-right chart is wider than a phone column, so narrow screens start
+	// it top-down; vertical charts already fit and keep the author's direction.
+	const preferred =
+		authored !== null && !wideScreen && (authored === "LR" || authored === "RL") ? "TB" : authored;
+	const [chosen, setChosen] = useState<{ source: string; direction: FlowDirection } | null>(null);
+	const direction = chosen !== null && chosen.source === source ? chosen.direction : preferred;
+	const diagramSource =
+		source !== null && direction !== null ? setFlowchartDirection(source, direction) : source;
+	const directionMenu =
+		source !== null && authored !== null && direction !== null ? (
+			<DirectionMenu
+				value={direction}
+				authored={authored}
+				onChange={(next) => setChosen({ source, direction: next })}
+			/>
+		) : null;
+
+	// Pull the raw diagram text out of the (always-mounted) <pre> so the diagram
+	// view and the copy button share one source of truth. Select the code
+	// block's own <pre> (tagged by `Pre` below), not the first <pre> in the
+	// card: when a diagram fails, MermaidDiagram's error card puts the message
+	// in a <pre> that sits *before* the code pane, and a bare "pre" lookup
+	// would feed that message back into mermaid on the next re-render — each
+	// pass wrapping the last error, never recovering until a reload.
+	function codePre() {
+		return containerRef.current?.querySelector("pre[data-code-source]") ?? null;
+	}
+
+	useEffect(() => {
+		if (!isMermaid) return;
+		setSource(codePre()?.textContent ?? "");
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [isMermaid, children]);
+
+	function getCopyText() {
+		return codePre()?.textContent ?? "";
+	}
+
+	return (
+		<div
+			ref={containerRef}
+			className="overflow-hidden rounded-lg border border-code-border bg-code-bg"
+		>
+			<CodeFrameHeader
+				label={label}
+				actions={
+					<>
+						{isMermaid ? <ViewToggle view={view} onChange={setView} toggleId={toggleId} /> : null}
+						{showDiagram ? directionMenu : null}
+						<CopyButton getText={getCopyText} />
+					</>
+				}
+			/>
+			{isMermaid ? (
+				<CrossFade
+					active={showDiagram ? "diagram" : "code"}
+					panes={[
+						{
+							key: "diagram",
+							node:
+								diagramSource !== null ? (
+									<MermaidDiagram source={diagramSource} toolbar={directionMenu} />
+								) : null,
+						},
+						{
+							key: "code",
+							node: <InsideCodeFrame.Provider value={true}>{children}</InsideCodeFrame.Provider>,
+						},
+					]}
+				/>
+			) : (
+				<InsideCodeFrame.Provider value={true}>{children}</InsideCodeFrame.Provider>
+			)}
+		</div>
+	);
+}
+
+const PRE_CLASS =
+	"font-mono font-normal leading-[1.62] text-[length:var(--size-sm)] text-code-fg overflow-x-auto";
+
+type PreProps = ComponentPropsWithoutRef<"pre"> & { "data-language"?: string };
+
+/**
+ * MDXProvider `pre` override. Inside a `Figure`-rendered card it's just the bare
+ * styled `<pre>` (the card supplies the header/copy button); standalone, it wraps
+ * itself in `CodeFrame` so it still gets the full treatment.
+ */
+export function Pre(props: PreProps) {
+	const insideFrame = useContext(InsideCodeFrame);
+	// `data-code-source` is what CodeFrame's source/copy lookups select on; both
+	// the in-figure and the standalone <pre> carry it.
+	if (insideFrame) {
+		return <pre {...props} data-code-source className={PRE_CLASS} />;
+	}
+	const { "data-language": language, ...rest } = props;
+	return (
+		<CodeFrame language={language}>
+			<pre {...rest} data-language={language} data-code-source className={PRE_CLASS} />
+		</CodeFrame>
+	);
+}
+
+type FigureProps = ComponentPropsWithoutRef<"figure"> & {
+	"data-rehype-pretty-code-figure"?: string;
+};
+
+function textContentOf(node: ReactNode): string {
+	if (typeof node === "string") return node;
+	if (typeof node === "number") return String(node);
+	if (Array.isArray(node)) return node.map(textContentOf).join("");
+	if (isValidElement(node)) return textContentOf((node.props as { children?: ReactNode }).children);
+	return "";
+}
+
+/**
+ * MDXProvider `figure` override. Only rehype-pretty-code's code figures (tagged
+ * with `data-rehype-pretty-code-figure`) get the framed treatment; any
+ * other `<figure>` (e.g. wrapping an image) renders unchanged.
+ */
+export function Figure({ children, ...props }: FigureProps) {
+	if (!("data-rehype-pretty-code-figure" in props)) {
+		return <figure {...props}>{children}</figure>;
+	}
+
+	const nodes = Children.toArray(children).filter(isValidElement) as ReactElement<
+		Record<string, unknown>
+	>[];
+	const titleNode = nodes.find((node) => "data-rehype-pretty-code-title" in node.props);
+	// The figure only ever contains the optional title and the <pre>; avoid comparing
+	// component identity (it changes under Fast Refresh) and take the non-title child.
+	const preNode = nodes.find((node) => node !== titleNode);
+	const title = titleNode ? textContentOf(titleNode) : undefined;
+	const language = preNode ? (preNode.props["data-language"] as string | undefined) : undefined;
+
+	return (
+		<CodeFrame title={title} language={language}>
+			{preNode}
+		</CodeFrame>
+	);
+}