@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/ui/PageNav.tsx

@@ -0,0 +1,77 @@
+import { useState, type HTMLAttributes, type ReactNode } from "react";
+import { motion } from "framer-motion";
+import { Icon } from "./Icon";
+import { TRANSITIONS } from "../motion";
+
+export interface PageNavLink {
+	label: ReactNode;
+	href: string;
+	/** Overrides the default "Previous" / "Next" eyebrow. */
+	eyebrow?: ReactNode;
+}
+
+export interface PageNavProps extends HTMLAttributes<HTMLDivElement> {
+	prev?: PageNavLink;
+	next?: PageNavLink;
+}
+
+function Side({ item, dir }: { item: PageNavLink; dir: "prev" | "next" }) {
+	const [hover, setHover] = useState(false);
+	const prev = dir === "prev";
+	return (
+		<motion.a
+			href={item.href}
+			onMouseEnter={() => setHover(true)}
+			onMouseLeave={() => setHover(false)}
+			animate={{ y: hover ? -2 : 0 }}
+			whileTap={{ y: 0, scale: 0.995 }}
+			transition={TRANSITIONS.snap}
+			className={
+				"flex min-w-0 flex-1 flex-col gap-1 rounded-lg border bg-surface-card px-4 py-3 no-underline transition-shadow " +
+				(prev ? "items-start text-left" : "items-end text-right") +
+				" " +
+				(hover ? "border-border-accent shadow-sm" : "border-border-default")
+			}
+		>
+			<span className="flex items-center gap-1 font-mono text-[length:var(--size-2xs)] font-semibold uppercase tracking-[var(--tracking-caps)] text-text-subtle">
+				{prev ? (
+					<motion.span
+						animate={{ x: hover ? -2 : 0 }}
+						transition={TRANSITIONS.snap}
+						className="inline-flex"
+					>
+						<Icon name="arrow-left" size={12} />
+					</motion.span>
+				) : null}
+				{item.eyebrow ?? (prev ? "Previous" : "Next")}
+				{prev ? null : (
+					<motion.span
+						animate={{ x: hover ? 2 : 0 }}
+						transition={TRANSITIONS.snap}
+						className="inline-flex"
+					>
+						<Icon name="arrow-right" size={12} />
+					</motion.span>
+				)}
+			</span>
+			<span
+				className={
+					"max-w-full break-words text-[15px] leading-normal font-semibold transition-colors " +
+					(hover ? "text-text-accent" : "text-text-heading")
+				}
+			>
+				{item.label}
+			</span>
+		</motion.a>
+	);
+}
+
+/** Prev/next page cards below the prose column. */
+export function PageNav({ prev, next, className, ...rest }: PageNavProps) {
+	return (
+		<div className={"flex gap-3" + (className ? " " + className : "")} {...rest}>
+			{prev ? <Side item={prev} dir="prev" /> : <span className="flex-1" />}
+			{next ? <Side item={next} dir="next" /> : <span className="flex-1" />}
+		</div>
+	);
+}

package/client/ui/ResizeHandle.tsx

@@ -0,0 +1,201 @@
+import { motion } from "framer-motion";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { TRANSITIONS } from "../motion";
+
+/** Gap between the content's edge and the resize handle's resting line. */
+const HANDLE_INSET = 12;
+/** Hover zone width: covers the inset gap plus room on either side of the line. */
+const HANDLE_ZONE = 40;
+/** Height of the resting pill. */
+const PILL_HEIGHT = 40;
+
+type HandleState = "idle" | "hover" | "drag";
+
+const handleBar: Record<
+	HandleState,
+	{ width: number; height: string; opacity: number; backgroundColor: string }
+> = {
+	// A short muted pill at rest, so the affordance is discoverable.
+	idle: {
+		width: 3,
+		height: `${PILL_HEIGHT}px`,
+		opacity: 0.6,
+		backgroundColor: "var(--border-default)",
+	},
+	// Full-height line on hover.
+	hover: { width: 2, height: "100%", opacity: 1, backgroundColor: "var(--border-default)" },
+	// Thicker and teal while dragging.
+	drag: { width: 4, height: "100%", opacity: 1, backgroundColor: "var(--surface-accent)" },
+};
+
+/**
+ * Resize handle just outside one edge of a content block. The hover zone is
+ * wide (it spans the inset gap) so it's easy to find; the bar itself rests as
+ * a short pill, grows to a full-height line on hover, and thickens + turns
+ * teal mid-drag. For a page-height content block the pill sticks to the
+ * viewport's vertical centre (rather than the block's, which is usually off
+ * screen) so it's always in view; anchored panels are already viewport-bound,
+ * so theirs is simply centred.
+ *
+ * Two modes:
+ * - Default: the content is centred in the area marked with
+ *   `data-content-area`, so moving one edge by `d` changes the width by `2d` —
+ *   computed from the content's centre rather than accumulated deltas so the
+ *   drag can't drift. Widths are clamped to [minWidth, maxWidth] and to the
+ *   content area so the block never runs under the surrounding chrome.
+ * - `anchored`: the panel is flush against one edge of the layout (the docked
+ *   sidebar on the left with `side="right"`, the toc rail on the right with
+ *   `side="left"`), so the dragged edge maps 1:1 to the width with no doubling
+ *   or centring, and the width is only clamped to [minWidth, maxWidth].
+ */
+export function ResizeHandle({
+	side,
+	container,
+	onResize,
+	label,
+	minWidth,
+	maxWidth,
+	anchored = false,
+}: {
+	side: "left" | "right";
+	container: React.RefObject<HTMLDivElement | null>;
+	onResize: (width: number) => void;
+	label: string;
+	minWidth: number;
+	maxWidth: number;
+	/** Panel flush against the layout edge opposite `side`, so the drag maps 1:1 to the width. */
+	anchored?: boolean;
+}) {
+	const [hovered, setHovered] = useState(false);
+	const [dragging, setDragging] = useState(false);
+	const draggingRef = useRef(false);
+	/** Pointer distance from the resting bar at grab time, so a press anywhere
+	 * in the zone drags relative to it instead of snapping the bar under the cursor. */
+	const grabOffset = useRef(0);
+
+	useEffect(() => {
+		return () => {
+			if (!draggingRef.current) return;
+			draggingRef.current = false;
+			document.body.style.cursor = "";
+			document.body.style.userSelect = "";
+		};
+	}, []);
+
+	const clamp = useCallback(
+		(px: number) => {
+			// Anchored panels aren't centred in a content area — clamp to the
+			// configured bounds only.
+			if (anchored) return Math.min(maxWidth, Math.max(minWidth, Math.round(px)));
+			const area = container.current?.closest("[data-content-area]");
+			const available = area instanceof HTMLElement ? area.clientWidth : maxWidth;
+			return Math.min(Math.min(maxWidth, available), Math.max(minWidth, Math.round(px)));
+		},
+		[container, minWidth, maxWidth, anchored],
+	);
+
+	const onPointerDown = useCallback(
+		(event: React.PointerEvent<HTMLDivElement>) => {
+			event.preventDefault();
+			if (anchored && container.current) {
+				// Pointer distance past the panel's dragged edge, so the drag stays
+				// relative to where it was grabbed instead of snapping the edge to the cursor.
+				const rect = container.current.getBoundingClientRect();
+				grabOffset.current =
+					side === "right" ? event.clientX - rect.right : rect.left - event.clientX;
+			} else if (container.current) {
+				const rect = container.current.getBoundingClientRect();
+				const centre = rect.left + rect.width / 2;
+				const half = side === "right" ? event.clientX - centre : centre - event.clientX;
+				grabOffset.current = half - (rect.width / 2 + HANDLE_INSET);
+			} else {
+				grabOffset.current = 0;
+			}
+			draggingRef.current = true;
+			setDragging(true);
+			try {
+				event.currentTarget.setPointerCapture(event.pointerId);
+			} catch {
+				// Not a live pointer (synthetic event); the drag still works while the cursor stays in the zone.
+			}
+			document.body.style.cursor = "col-resize";
+			document.body.style.userSelect = "none";
+		},
+		[container, side, anchored],
+	);
+
+	const onPointerMove = useCallback(
+		(event: React.PointerEvent<HTMLDivElement>) => {
+			if (!draggingRef.current || !container.current) return;
+			if (anchored) {
+				const rect = container.current.getBoundingClientRect();
+				const edge = side === "right" ? event.clientX - rect.left : rect.right - event.clientX;
+				onResize(clamp(edge - grabOffset.current));
+				return;
+			}
+			const rect = container.current.getBoundingClientRect();
+			const centre = rect.left + rect.width / 2;
+			const half = side === "right" ? event.clientX - centre : centre - event.clientX;
+			onResize(clamp((half - HANDLE_INSET - grabOffset.current) * 2));
+		},
+		[container, onResize, side, clamp, anchored],
+	);
+
+	const onPointerUp = useCallback((event: React.PointerEvent<HTMLDivElement>) => {
+		draggingRef.current = false;
+		setDragging(false);
+		if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+			event.currentTarget.releasePointerCapture(event.pointerId);
+		}
+		document.body.style.cursor = "";
+		document.body.style.userSelect = "";
+	}, []);
+
+	const state: HandleState = dragging ? "drag" : hovered ? "hover" : "idle";
+	// Centre the bar on the inset line: the zone starts at the content edge and
+	// extends outward, so the line sits HANDLE_INSET in from the zone's inner edge.
+	// The left-anchored sidebar sits flush beside the main column, so rather than
+	// overhang into it the zone straddles the panel's border, centred on it. The
+	// right-anchored toc rail has a gutter on its left and its list draws its own
+	// left border, so its bar sits out in the gutter like the centred handles.
+	const zoneStyle =
+		anchored && side === "right"
+			? { right: -HANDLE_ZONE / 2 }
+			: side === "right"
+				? { right: -HANDLE_ZONE, paddingLeft: HANDLE_INSET }
+				: { left: -HANDLE_ZONE, paddingRight: HANDLE_INSET };
+
+	return (
+		<div
+			role="separator"
+			aria-orientation="vertical"
+			aria-label={label}
+			onPointerEnter={() => setHovered(true)}
+			onPointerLeave={() => setHovered(false)}
+			onPointerDown={onPointerDown}
+			onPointerMove={onPointerMove}
+			onPointerUp={onPointerUp}
+			onPointerCancel={onPointerUp}
+			style={{ width: HANDLE_ZONE, ...zoneStyle }}
+			className={
+				"absolute inset-y-0 z-10 flex cursor-col-resize " +
+				(anchored
+					? "items-center " + (side === "right" ? "justify-center" : "justify-end")
+					: // A column so the sticky pill can slide along the zone's full height.
+						"flex-col " + (side === "right" ? "items-start" : "items-end"))
+			}
+		>
+			<motion.div
+				initial={false}
+				animate={handleBar[state]}
+				transition={{
+					...TRANSITIONS.snap,
+					opacity: TRANSITIONS.fast,
+					backgroundColor: TRANSITIONS.fast,
+				}}
+				className={"shrink-0 rounded-full" + (anchored ? "" : " sticky")}
+				style={anchored ? undefined : { top: `calc(50vh - ${PILL_HEIGHT / 2}px)` }}
+			/>
+		</div>
+	);
+}

package/client/ui/SearchDialog.tsx

@@ -0,0 +1,187 @@
+import {
+	useEffect,
+	useState,
+	type HTMLAttributes,
+	type KeyboardEvent,
+	type ReactNode,
+} from "react";
+import { AnimatePresence, motion, type MotionProps } from "framer-motion";
+import { Icon } from "./Icon";
+import { Kbd } from "./Kbd";
+import { TRANSITIONS, VARIANTS } from "../motion";
+
+export interface SearchResult {
+	title: ReactNode;
+	excerpt?: ReactNode;
+	path?: string;
+	/** Display path, e.g. "<rootName>/<relative path>"; shown above the title. */
+	label?: ReactNode;
+	/** Matched query terms; occurrences are highlighted in each field. */
+	terms?: string[];
+}
+
+function escapeRegExp(input: string): string {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Wrap every case-insensitive occurrence of `terms` in `text` with `<mark>`. */
+function highlight(text: ReactNode, terms: string[] | undefined): ReactNode {
+	if (typeof text !== "string" || !terms || terms.length === 0) return text;
+	const pattern = terms
+		.filter((term) => term.length > 0)
+		.sort((first, second) => second.length - first.length)
+		.map(escapeRegExp)
+		.join("|");
+	if (pattern === "") return text;
+	const parts = text.split(new RegExp(`(${pattern})`, "gi"));
+	return parts.map((part, index) =>
+		index % 2 === 1 ? (
+			<mark key={index} className="rounded-sm bg-surface-accent-soft text-text-accent">
+				{part}
+			</mark>
+		) : (
+			part
+		),
+	);
+}
+
+// `results` shadows a legacy global HTML attribute (a WebKit `<input>` prop
+// React still types on `HTMLAttributes`); `Omit` it, along with the
+// motion.div-owned event props, before extending.
+export interface SearchDialogProps extends Omit<
+	HTMLAttributes<HTMLDivElement>,
+	"results" | "onSelect" | keyof MotionProps
+> {
+	open?: boolean;
+	query?: string;
+	results?: SearchResult[];
+	onQueryChange?: (query: string) => void;
+	onSelect?: (result: SearchResult) => void;
+	onClose?: () => void;
+}
+
+const STAGGER_CAP = 5;
+
+/** ⌘K command palette: search the served folder without leaving the page. */
+export function SearchDialog({
+	open = true,
+	query = "",
+	results = [],
+	onQueryChange,
+	onSelect,
+	onClose,
+	className,
+	...rest
+}: SearchDialogProps) {
+	const [highlighted, setHighlighted] = useState(0);
+
+	useEffect(() => {
+		setHighlighted(0);
+	}, [query, results, open]);
+
+	function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+		if (event.key === "ArrowDown") {
+			event.preventDefault();
+			setHighlighted((current) => Math.min(current + 1, Math.max(results.length - 1, 0)));
+		} else if (event.key === "ArrowUp") {
+			event.preventDefault();
+			setHighlighted((current) => Math.max(current - 1, 0));
+		} else if (event.key === "Enter") {
+			const result = results[highlighted];
+			if (result) {
+				event.preventDefault();
+				onSelect?.(result);
+			}
+		} else if (event.key === "Escape") {
+			event.preventDefault();
+			onClose?.();
+		}
+	}
+
+	return (
+		<AnimatePresence>
+			{open ? (
+				<motion.div
+					key="scrim"
+					onClick={onClose}
+					{...VARIANTS.scrim}
+					className="fixed inset-0 z-[var(--z-modal)] flex justify-center bg-[var(--scrim)] pt-[10vh] backdrop-blur-sm"
+				>
+					<motion.div
+						onClick={(event) => event.stopPropagation()}
+						onKeyDown={handleKeyDown}
+						{...VARIANTS.pop}
+						className={
+							"w-[560px] max-w-[92vw] self-start overflow-hidden rounded-xl border border-border-default bg-surface-raised shadow-lg" +
+							(className ? " " + className : "")
+						}
+						{...rest}
+					>
+						<div className="flex h-12 items-center gap-3 border-b border-border-subtle px-4">
+							<Icon name="search" size="md" className="text-text-subtle" />
+							<input
+								autoFocus
+								data-bare-focus
+								value={query}
+								onChange={(event) => onQueryChange?.(event.target.value)}
+								placeholder="Search docs"
+								className="flex-1 border-0 bg-transparent text-[18px] font-normal text-text-body outline-none placeholder:text-text-subtle"
+							/>
+							<Kbd>esc</Kbd>
+						</div>
+						<motion.div
+							layout
+							transition={TRANSITIONS.glide}
+							className="max-h-80 overflow-y-auto p-2"
+						>
+							{results.length === 0 ? (
+								<div className="p-6 text-center text-[13px] leading-normal font-medium text-text-subtle">
+									No matches
+								</div>
+							) : (
+								results.map((result, index) => {
+									const active = index === highlighted;
+									return (
+										<motion.div
+											key={(result.path ?? "") + index}
+											layout
+											initial={{ opacity: 0, y: 4 }}
+											animate={{ opacity: 1, y: 0 }}
+											transition={{
+												...TRANSITIONS.glide,
+												delay: Math.min(index, STAGGER_CAP - 1) * 0.02,
+											}}
+											onMouseEnter={() => setHighlighted(index)}
+											onClick={() => onSelect?.(result)}
+											className={
+												"flex cursor-pointer items-start gap-3 rounded-md p-2.5 " +
+												(active ? "bg-surface-hover" : "bg-transparent")
+											}
+										>
+											<Icon name="file-text" size="sm" className="mt-0.5 text-text-subtle" />
+											<div className="min-w-0 flex-1">
+												{result.label ? (
+													<div className="overflow-hidden text-ellipsis whitespace-nowrap font-mono text-[length:var(--size-2xs)] text-text-subtle">
+														{highlight(result.label, result.terms)}
+													</div>
+												) : null}
+												<div className="text-[13px] leading-normal font-semibold text-text-heading">
+													{highlight(result.title, result.terms)}
+												</div>
+												{result.excerpt ? (
+													<div className="mt-px overflow-hidden text-ellipsis whitespace-nowrap text-[12px] font-normal text-text-muted">
+														{highlight(result.excerpt, result.terms)}
+													</div>
+												) : null}
+											</div>
+										</motion.div>
+									);
+								})
+							)}
+						</motion.div>
+					</motion.div>
+				</motion.div>
+			) : null}
+		</AnimatePresence>
+	);
+}

package/client/ui/Tag.tsx

@@ -0,0 +1,44 @@
+import { useState, type HTMLAttributes } from "react";
+import { Icon } from "./Icon";
+
+export interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+	/** Selected/filtering state. */
+	active?: boolean;
+	/** Renders a dismiss affordance. */
+	onRemove?: () => void;
+}
+
+/** Small pill used for filter chips and metadata labels. */
+export function Tag({ children, onRemove, active, className, ...rest }: TagProps) {
+	const [hover, setHover] = useState(false);
+	return (
+		<span
+			onMouseEnter={() => setHover(true)}
+			onMouseLeave={() => setHover(false)}
+			className={
+				"inline-flex h-6 items-center gap-1.5 rounded-pill border font-sans font-medium leading-normal text-[length:var(--size-sm)] transition-colors " +
+				(onRemove ? "pr-1.5 pl-2.5" : "px-2.5") +
+				" " +
+				(active
+					? "border-teal-200 bg-surface-accent-soft text-text-accent"
+					: hover
+						? "border-border-default bg-surface-hover text-text-muted"
+						: "border-border-default bg-surface-sunken text-text-muted") +
+				(className ? " " + className : "")
+			}
+			{...rest}
+		>
+			{children}
+			{onRemove ? (
+				<button
+					type="button"
+					onClick={onRemove}
+					aria-label="Remove"
+					className="inline-flex cursor-pointer rounded-pill border-0 bg-transparent p-0.5 text-inherit"
+				>
+					<Icon name="x" size={12} />
+				</button>
+			) : null}
+		</span>
+	);
+}

package/client/ui/Toast.tsx

@@ -0,0 +1,189 @@
+import { useEffect, type CSSProperties, type ReactNode } from "react";
+import {
+	CheckmarkIcon,
+	ErrorIcon,
+	ToastBar,
+	Toaster,
+	toast,
+	useToasterStore,
+	type Toast as HotToast,
+} from "react-hot-toast";
+import { Icon } from "./Icon";
+import { nextCount } from "./toast-count";
+import { docModuleCache } from "../doc-module-cache";
+
+export type ToastTone = "info" | "ok" | "warn" | "danger";
+
+export interface ToastInput {
+	tone: ToastTone;
+	/** The whole toast — one line, sentence case, human-written. */
+	text: string;
+	/** Lucide icon name overriding the tone's icon (e.g. "download", "trash-2"). */
+	icon?: string;
+	/** Pushes sharing a key collapse into one card: repeat push = same card, ×N counter, bounce, dismiss timer restarted. */
+	dedupeKey?: string;
+}
+
+const TONE_FG: Record<ToastTone, string> = {
+	info: "text-status-info-fg",
+	ok: "text-status-ok-fg",
+	warn: "text-status-warn-fg",
+	danger: "text-status-danger-fg",
+};
+
+// react-hot-toast only exposes live state through this hook, so the module
+// scope below can't just read a store synchronously the way `pushToast` (a
+// plain function, called from outside React) needs to. Instead a child
+// component mirrors the hook's state into `liveIds` on every change; that
+// mirror is what `nextCount` consults. Driving it off `visible` (not just
+// presence in the list, which includes toasts mid fade-out) is what keeps
+// counting correct under pause-on-hover: a hovered toast's dismiss timer is
+// paused, not fired, so it stays "live" and a repeat push still increments
+// its counter instead of resetting to 1.
+let liveIds = new Set<string>();
+const counts = new Map<string, number>();
+
+function LiveIdMirror() {
+	const { toasts } = useToasterStore();
+	useEffect(() => {
+		liveIds = new Set(toasts.filter((item) => item.visible).map((item) => item.id));
+	}, [toasts]);
+	return null;
+}
+
+/**
+ * react-hot-toast sets each bar's enter/exit `animation` inline (see its
+ * source), so a plain class on `ToastBar` itself would lose to that inline
+ * style — or, with `!important`, would clobber the exit animation too. This
+ * wrapper carries the attention-bounce class instead, one layer out from
+ * where react-hot-toast writes its own animation.
+ */
+function Bump({ pulse, children }: { pulse: number; children: ReactNode }) {
+	const bumpClass = pulse > 0 ? (pulse % 2 === 1 ? "toast-bump-a" : "toast-bump-b") : undefined;
+	return <div className={bumpClass}>{children}</div>;
+}
+
+function toneIcon(tone: ToastTone, iconName: string | undefined) {
+	if (iconName) return <Icon name={iconName} size="md" className={TONE_FG[tone]} />;
+	switch (tone) {
+		case "ok":
+			return <CheckmarkIcon primary="var(--status-ok-fg)" secondary="var(--surface-raised)" />;
+		case "danger":
+			return <ErrorIcon primary="var(--status-danger-fg)" secondary="var(--surface-raised)" />;
+		case "warn":
+			return <Icon name="triangle-alert" size="md" className="text-status-warn-fg" />;
+		case "info":
+			return null;
+	}
+}
+
+/**
+ * Queues a toast; repeat pushes sharing `dedupeKey` collapse into the same
+ * card (message updates, ×N counter, attention bounce, dismiss timer
+ * restarted) instead of stacking a second one. Returns the toast's id.
+ */
+export function pushToast(input: ToastInput): string {
+	const id = input.dedupeKey;
+	const count = input.dedupeKey ? nextCount(liveIds, counts, input.dedupeKey) : 1;
+	const message =
+		count > 1 ? (
+			<>
+				{input.text}
+				<span className="ml-2 rounded-pill border border-border-default bg-surface-sunken px-1.5 text-[11px] tabular-nums text-text-muted">
+					×{count}
+				</span>
+			</>
+		) : (
+			input.text
+		);
+	const toastId = toast.custom(
+		(liveToast: HotToast) => (
+			<Bump pulse={count - 1}>
+				<ToastBar toast={{ ...liveToast, message }} />
+			</Bump>
+		),
+		{
+			id,
+			duration: 4000,
+			// ToastBar picks its enter/exit direction from the toast, not the
+			// Toaster; without this it animates as if the stack were top-center.
+			position: "bottom-right",
+			icon: toneIcon(input.tone, input.icon),
+		},
+	);
+	// The mirror only catches up after React commits; mark the id live now so
+	// a second push in the same tick still counts as a repeat.
+	liveIds.add(toastId);
+	return toastId;
+}
+
+/** Re-exported for symmetry with `pushToast`. */
+export const dismissToast = toast.dismiss;
+
+const TOAST_STYLE: CSSProperties = {
+	background: "var(--surface-raised)",
+	color: "var(--text-heading)",
+	border: "1px solid var(--border-default)",
+	borderRadius: 8,
+	boxShadow: "var(--shadow-toast)",
+	font: "500 14px/1.4 var(--font-sans)",
+	maxWidth: 360,
+};
+
+/** Fixed bottom-right stack. Mount once near the app root. */
+export function ToastStack() {
+	// The server names the doc that was edited (`mdxserve:doc-changed`, sent
+	// from its file watcher). Vite's own `vite:afterUpdate` can't be used for
+	// this: a doc module has no HMR boundary, so the update is attributed to
+	// the importer that accepted it (App.tsx), and the Tailwind rebuild the
+	// edit triggers shows up as a second update for app.css.
+	useEffect(() => {
+		if (!import.meta.hot) return;
+		// The event covers every doc under every mounted root, so keep only the
+		// docs this tab has actually loaded (the old vite:afterUpdate toast was
+		// scoped to loaded modules the same way) — an agent editing forty
+		// unrelated files shouldn't rain toasts on a reader. Keyed by path so a
+		// burst of saves to one doc refreshes a single card (counter + bounce,
+		// timer restarted) instead of stacking copies.
+		const handleDocChanged = (data: {
+			files?: Array<{ path: string; root: string; rel: string }>;
+		}) => {
+			const files = (data?.files ?? []).filter((file) => docModuleCache.has(file.path));
+			const [first] = files;
+			if (!first) return;
+			if (files.length === 1) {
+				pushToast({
+					tone: "info",
+					text: `Reloaded ${first.rel}`,
+					dedupeKey: `reload:${first.path}`,
+				});
+			} else {
+				pushToast({
+					tone: "info",
+					text: `Reloaded ${files.length} docs`,
+					dedupeKey: "reload:many",
+				});
+			}
+		};
+		import.meta.hot.on("mdxserve:doc-changed", handleDocChanged);
+		return () => {
+			import.meta.hot?.off?.("mdxserve:doc-changed", handleDocChanged);
+		};
+	}, []);
+
+	return (
+		<>
+			<LiveIdMirror />
+			{/* Inline style, not a class: goober (react-hot-toast's runtime CSS-in-JS)
+			    injects the base toast class after this stylesheet loads, so only an
+			    inline style is guaranteed to win. The custom properties still resolve
+			    at computed-style time, so light/dark both come through correctly. */}
+			<Toaster
+				position="bottom-right"
+				gutter={8}
+				containerStyle={{ zIndex: "var(--z-toast)", inset: 16 }}
+				toastOptions={{ duration: 4000, style: TOAST_STYLE }}
+			/>
+		</>
+	);
+}