@karimsa/mdxserve 0.0.0-stage → 0.2.0

package/client/shell/AppShell.tsx

@@ -0,0 +1,401 @@
+import { AnimatePresence, motion, useSpring } from "framer-motion";
+import { useAtomValue } from "jotai";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { trpc } from "../api";
+import { DocView } from "../DocView";
+import { HomeView } from "../HomeView";
+import { useDebounced } from "../hooks";
+import { ListingView } from "../ListingView";
+import { fadeRise, TRANSITIONS } from "../motion";
+import { useTheme } from "../theme";
+import {
+	docModuleCache,
+	docMtime,
+	shellInfo,
+	useFolderListing,
+	useTree,
+	type Route,
+	type TreeNode,
+} from "../router";
+import type { ExportFormat } from "../../src/export/service";
+import { exportDocFromViewer } from "../export-doc";
+import { Breadcrumb, type BreadcrumbItem } from "../ui/Breadcrumb";
+import { PageNav, type PageNavLink } from "../ui/PageNav";
+import { SearchDialog, type SearchResult } from "../ui/SearchDialog";
+import { Footer } from "./Footer";
+import { NotFoundView } from "./NotFoundView";
+import { Sidebar } from "./Sidebar";
+import { TocRail } from "./TocRail";
+import { TopBar } from "./TopBar";
+import { useContentWidth, useDocMaxWidth } from "./use-doc-width";
+import { DESKTOP_MEDIA } from "../platform";
+import { docWidthAtom, LISTING_MAX_WIDTH, LISTING_MIN_WIDTH, listingWidthAtom } from "../state";
+
+const SIDEBAR_STORAGE_KEY = "mdxserve-sidebar";
+const SEARCH_DEBOUNCE_MS = 120;
+
+function readStoredSidebarOpen(): boolean {
+	try {
+		const value = localStorage.getItem(SIDEBAR_STORAGE_KEY);
+		return value === null ? true : value === "1";
+	} catch {
+		return true;
+	}
+}
+
+function stripDocExt(name: string): string {
+	return name.replace(/\.mdx?$/i, "");
+}
+
+/** Depth-first doc order of the tree, matching the sidebar's rendering order. */
+function flattenDocs(nodes: TreeNode[] | null): TreeNode[] {
+	const result: TreeNode[] = [];
+	function walk(list: TreeNode[]) {
+		for (const node of list) {
+			if (node.isDoc) result.push(node);
+			if (node.children) walk(node.children);
+		}
+	}
+	if (nodes) walk(nodes);
+	return result;
+}
+
+/**
+ * Root name -> path segments; every segment is a folder link except a doc's
+ * last segment. Folder listings lead with the served directory's absolute
+ * path instead, with only the served root onwards being navigable. On the
+ * home page there's just the "mdxserve" crumb; everywhere else it's the
+ * leading crumb too, but only when the server serves more than one root.
+ */
+function breadcrumbItems(route: Route, rootsCount: number): BreadcrumbItem[] {
+	if (route.kind === "home") return [{ label: "mdxserve" }];
+
+	const items: BreadcrumbItem[] = [];
+	if (rootsCount > 1) items.push({ label: "mdxserve", href: "/" });
+
+	const rootDir = route.rootDir ?? "";
+	const rootName = route.rootName ?? "";
+
+	if (route.kind === "listing" && rootDir) {
+		// The server hands back its raw root, so split on either separator.
+		const parents = rootDir.split(/[\\/]/).filter(Boolean).slice(0, -1);
+		if (parents.length === 0) items.push({ label: "/" });
+		for (const parent of parents) items.push({ label: parent });
+	}
+
+	if (rootDir) items.push({ label: rootName, href: `${rootDir}/` });
+
+	const segments = route.path.slice(rootDir.length).split("/").filter(Boolean);
+	let acc = rootDir;
+	segments.forEach((segment, index) => {
+		acc += `/${segment}`;
+		const isLast = index === segments.length - 1;
+		const isDocLast = isLast && route.kind !== "listing";
+		items.push({ label: segment, href: isDocLast ? undefined : `${acc}/` });
+	});
+	return items;
+}
+
+/** Fraction of the content width a folder listing takes by default. */
+const LISTING_DEFAULT_FRACTION = 2 / 3;
+
+/**
+ * Spring-animated max-width for folder listings: the stored width when the user
+ * has dragged one, otherwise 2/3 of the content area's width.
+ */
+function useListingMaxWidth(contentWidth: number, stored: number | null) {
+	// glide, not snap: the width trails the drag slightly so the spring is felt.
+	const spring = useSpring(0, TRANSITIONS.glide);
+	const initialised = useRef(false);
+
+	// A layout effect so the first listing paint already has a real max-width
+	// (the wrapper binds the spring immediately and AnimatePresence skips the
+	// initial animation).
+	useLayoutEffect(() => {
+		if (contentWidth <= 0) return;
+		const fallback = Math.round(contentWidth * LISTING_DEFAULT_FRACTION);
+		const target = Math.min(
+			LISTING_MAX_WIDTH,
+			contentWidth,
+			Math.max(LISTING_MIN_WIDTH, stored ?? fallback),
+		);
+		// First measurement: land on the value without animating up from 0.
+		if (initialised.current) spring.set(target);
+		else {
+			spring.jump(target);
+			initialised.current = true;
+		}
+	}, [contentWidth, stored, spring]);
+
+	return spring;
+}
+
+export function AppShell({ route, navigate }: { route: Route; navigate: (path: string) => void }) {
+	const { theme, toggle } = useTheme();
+	const { roots } = useTree();
+
+	// The listing route's entries come from the server-embedded route JSON (or
+	// the navigation fetch) and are seeded into the query cache, so read them
+	// back *live* from there: when files are added/removed under the open
+	// folder, api.ts invalidates that query and this re-renders with the fresh
+	// entries — no route reload, no second fetch racing the invalidation.
+	const liveListing = useFolderListing(route.kind === "listing" ? route.path : "");
+	const listingRoute = useMemo((): Route | null => {
+		if (route.kind !== "listing") return null;
+		// A NOT_FOUND refetch means the folder was renamed or deleted on disk
+		// after it was opened: show that rather than its stale entries.
+		if (liveListing.notFound) {
+			return {
+				kind: "notfound",
+				path: route.path,
+				rootName: route.rootName,
+				rootDir: route.rootDir,
+			};
+		}
+		return liveListing.entries ? { ...route, entries: liveListing.entries } : route;
+	}, [route, liveListing.entries, liveListing.notFound]);
+	// Until the tree API answers, trust the count the server-rendered shell
+	// embedded so multi-root navigation doesn't flash in after first paint.
+	const rootCount = roots?.length ?? shellInfo.rootCount ?? 1;
+	// Neither "home" nor a bare "notfound" (before any doc/listing loaded)
+	// carries a path/root of its own; fall back to values every consumer below
+	// can key off safely.
+	const activePath = route.kind === "home" ? "" : route.path;
+	const activeRootDir = route.kind === "home" ? "" : (route.rootDir ?? "");
+
+	const [desktopOpen, setDesktopOpen] = useState(readStoredSidebarOpen);
+	const [mobileOpen, setMobileOpen] = useState(false);
+
+	const [searchOpen, setSearchOpen] = useState(false);
+	const [exporting, setExporting] = useState(false);
+	const listingWidth = useAtomValue(listingWidthAtom);
+	const docWidth = useAtomValue(docWidthAtom);
+	const contentRef = useRef<HTMLDivElement>(null);
+	const contentWidth = useContentWidth(contentRef);
+	const listingMaxWidth = useListingMaxWidth(contentWidth, listingWidth);
+	const docMaxWidth = useDocMaxWidth(contentWidth, docWidth);
+	const [query, setQuery] = useState("");
+	const debouncedQuery = useDebounced(query, SEARCH_DEBOUNCE_MS);
+	const { data: searchData, isError: searchIsError } = useQuery(
+		trpc.searchDocs.queryOptions(
+			{ query: debouncedQuery },
+			{ enabled: searchOpen, placeholderData: keepPreviousData, staleTime: 0 },
+		),
+	);
+	const results = searchIsError ? [] : (searchData?.results ?? []);
+
+	// Doc content can render asynchronously after this component's own commit
+	// (see DocView's onRendered / client/router.ts's initial-route bootstrap
+	// effect); TocRail keys its heading scan on this so it re-scans once the
+	// article is actually on the page, not just when `route.path` changes.
+	const [tocVersion, setTocVersion] = useState(0);
+	const bumpTocVersion = useCallback(() => {
+		setTocVersion((previous) => previous + 1);
+		// The doc module arrives after the browser's own hash jump, so honour a
+		// `#heading` in the URL once the headings exist.
+		const hash = window.location.hash.slice(1);
+		if (hash) {
+			const target = document.getElementById(decodeURIComponent(hash));
+			target?.scrollIntoView({ block: "start", behavior: "instant" });
+		}
+	}, []);
+
+	useEffect(() => {
+		try {
+			localStorage.setItem(SIDEBAR_STORAGE_KEY, desktopOpen ? "1" : "0");
+		} catch {
+			// private mode / storage disabled: the choice just won't persist
+		}
+	}, [desktopOpen]);
+
+	// The docked sidebar is hidden on folder views and the roots home page.
+	const sidebarHidden = route.kind === "listing" || route.kind === "home";
+
+	// Drawer rows are plain links handled by the router's global click
+	// delegation, not a per-row handler, so close the drawer on any navigation.
+	useEffect(() => {
+		setMobileOpen(false);
+	}, [activePath]);
+
+	// One export at a time: the trigger is disabled while a build runs, and the
+	// server queues builds anyway (see startServer).
+	const handleExport = useCallback(
+		async (format: ExportFormat) => {
+			if (route.kind !== "doc" || exporting) return;
+			setExporting(true);
+			try {
+				await exportDocFromViewer({ path: route.path, format });
+			} finally {
+				setExporting(false);
+			}
+		},
+		[route, exporting],
+	);
+
+	const handleToggleSidebar = useCallback(() => {
+		if (window.matchMedia(DESKTOP_MEDIA).matches) {
+			// A click here would otherwise silently flip (and persist) the
+			// preference for the next doc.
+			if (sidebarHidden) return;
+			setDesktopOpen((previous) => !previous);
+		} else {
+			setMobileOpen((previous) => !previous);
+		}
+	}, [sidebarHidden]);
+
+	// Global ⌘K / Ctrl+K to open search, from anywhere on the page.
+	useEffect(() => {
+		function onKeyDown(event: KeyboardEvent) {
+			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+				event.preventDefault();
+				setSearchOpen(true);
+			}
+		}
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, []);
+
+	const handleSelectResult = useCallback(
+		(result: SearchResult) => {
+			setSearchOpen(false);
+			if (result.path) navigate(result.path);
+		},
+		[navigate],
+	);
+
+	// The sidebar footer counts every doc across all mounted roots.
+	const docCount = useMemo(
+		() => (roots ?? []).reduce((sum, root) => sum + flattenDocs(root.tree).length, 0),
+		[roots],
+	);
+
+	// Prev/next is scoped to the root the open doc lives in, not every mounted root.
+	const activeTree = useMemo(() => {
+		if (route.kind !== "doc") return null;
+		return roots?.find((root) => root.dir === route.rootDir)?.tree ?? null;
+	}, [roots, route]);
+	const flatDocs = useMemo(() => flattenDocs(activeTree), [activeTree]);
+	const { prev, next } = useMemo((): { prev?: PageNavLink; next?: PageNavLink } => {
+		if (route.kind !== "doc") return {};
+		const index = flatDocs.findIndex((doc) => doc.path === route.path);
+		if (index === -1) return {};
+		const previousDoc = flatDocs[index - 1];
+		const nextDoc = flatDocs[index + 1];
+		return {
+			prev: previousDoc
+				? { label: stripDocExt(previousDoc.name), href: previousDoc.path }
+				: undefined,
+			next: nextDoc ? { label: stripDocExt(nextDoc.name), href: nextDoc.path } : undefined,
+		};
+	}, [flatDocs, route]);
+
+	function handleExitComplete() {
+		if (!location.hash) window.scrollTo({ top: 0, behavior: "instant" });
+	}
+
+	// A folder view is the file navigation, so the docked sidebar would repeat
+	// it; hide the column there (and on the roots home page) and let the
+	// content take the space.
+	const showSidebar = desktopOpen && !sidebarHidden;
+
+	return (
+		<div className="min-h-screen bg-surface-page">
+			<TopBar
+				homeHref="/"
+				hostLabel={location.host}
+				sidebar={{ open: showSidebar, onToggle: handleToggleSidebar }}
+				search={{ onOpen: () => setSearchOpen(true) }}
+				exportDoc={
+					route.kind === "doc" && shellInfo.sameMachine
+						? { pending: exporting, onExport: handleExport }
+						: undefined
+				}
+				theme={theme}
+				onToggleTheme={toggle}
+			/>
+			<div className="flex items-start">
+				<Sidebar
+					rootDir={activeRootDir}
+					activePath={activePath}
+					docCount={docCount}
+					singleRoot={rootCount <= 1}
+					desktopOpen={showSidebar}
+					mobileOpen={mobileOpen}
+					onCloseMobile={() => setMobileOpen(false)}
+				/>
+				<main className="flex flex-1 min-w-0 px-8 pt-10 pb-24">
+					{/* The resize handles clamp drags to this area, and the max-width
+					    springs track it, so content never runs under the toc rail. */}
+					<div ref={contentRef} data-content-area className="flex flex-1 min-w-0 justify-center">
+						<AnimatePresence mode="wait" initial={false} onExitComplete={handleExitComplete}>
+							<motion.div
+								key={activePath || "/"}
+								variants={fadeRise}
+								initial="initial"
+								animate="enter"
+								exit="exit"
+								className={
+									route.kind === "listing" || (route.kind === "doc" && docMaxWidth)
+										? "w-full"
+										: "w-full max-w-prose"
+								}
+								style={
+									route.kind === "listing"
+										? { maxWidth: listingMaxWidth }
+										: route.kind === "doc" && docMaxWidth
+											? { maxWidth: docMaxWidth }
+											: undefined
+								}
+							>
+								<Breadcrumb items={breadcrumbItems(route, rootCount)} />
+								<div className="mt-4">
+									{route.kind === "listing" ? (
+										listingRoute?.kind === "notfound" ? (
+											<NotFoundView route={listingRoute} />
+										) : (
+											<ListingView
+												route={listingRoute?.kind === "listing" ? listingRoute : route}
+												singleRoot={rootCount <= 1}
+											/>
+										)
+									) : route.kind === "doc" ? (
+										<DocView
+											path={route.path}
+											module={docModuleCache.get(route.path)}
+											onRendered={bumpTocVersion}
+										/>
+									) : route.kind === "home" ? (
+										<HomeView route={route} />
+									) : (
+										<NotFoundView route={route} />
+									)}
+								</div>
+								{route.kind === "doc" && (prev || next) ? (
+									<div data-print-hide className="mt-16">
+										<PageNav prev={prev} next={next} />
+									</div>
+								) : null}
+								{route.kind === "doc" ? (
+									<Footer
+										label={route.rootName + route.path.slice(route.rootDir.length)}
+										mtime={route.mtime ?? docMtime(route.path)}
+									/>
+								) : null}
+							</motion.div>
+						</AnimatePresence>
+					</div>
+					{route.kind === "doc" ? <TocRail path={route.path} version={tocVersion} /> : null}
+				</main>
+			</div>
+			<SearchDialog
+				open={searchOpen}
+				query={query}
+				results={results}
+				onQueryChange={setQuery}
+				onClose={() => setSearchOpen(false)}
+				onSelect={handleSelectResult}
+			/>
+		</div>
+	);
+}

package/client/shell/Footer.tsx

@@ -0,0 +1,33 @@
+import { Icon } from "../ui/Icon";
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+
+function pluralize(count: number, unit: string): string {
+	return `${count} ${unit}${count === 1 ? "" : "s"} ago`;
+}
+
+/** "edited just now / N minutes ago / N hours ago / N days ago / a date". */
+function formatEdited(mtime: number | undefined): string {
+	if (mtime == null) return "unknown edit time";
+	const diff = Date.now() - mtime;
+	if (diff < MINUTE) return "edited just now";
+	if (diff < HOUR) return `edited ${pluralize(Math.floor(diff / MINUTE), "minute")}`;
+	if (diff < DAY) return `edited ${pluralize(Math.floor(diff / HOUR), "hour")}`;
+	if (diff < WEEK) return `edited ${pluralize(Math.floor(diff / DAY), "day")}`;
+	return `edited ${new Date(mtime).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" })}`;
+}
+
+/** Names the source file below a doc's content — the reader should never lose track of it. */
+export function Footer({ label, mtime }: { label: string; mtime?: number }) {
+	return (
+		<div className="mt-8 flex items-center gap-2 font-sans font-medium leading-normal text-[length:var(--size-sm)] text-text-subtle">
+			<Icon name="file-text" size="sm" strokeWidth="light" />
+			<span className="font-mono text-[length:var(--size-xs)]">{label}</span>
+			<span>·</span>
+			<span>{formatEdited(mtime)}</span>
+		</div>
+	);
+}

package/client/shell/NotFoundView.tsx

@@ -0,0 +1,22 @@
+import type { Route } from "../router";
+
+export function NotFoundView({ route }: { route: Extract<Route, { kind: "notfound" }> }) {
+	return (
+		<div>
+			<h1 className="mb-4 font-sans font-bold leading-[1.2] text-[length:var(--size-3xl)] text-text-heading">
+				Not found
+			</h1>
+			<p className="mb-6">
+				<code className="rounded-sm border border-border-default bg-surface-card px-1.5 py-0.5 font-mono text-[length:var(--size-xs)] text-text-muted">
+					{route.path}
+				</code>
+			</p>
+			<a
+				href={route.rootDir ? `${route.rootDir}/` : "/"}
+				className="text-[13px] font-semibold text-text-accent hover:text-text-link-hover"
+			>
+				Back to {route.rootName ?? "home"}
+			</a>
+		</div>
+	);
+}

package/client/shell/Sidebar.tsx

@@ -0,0 +1,169 @@
+import { AnimatePresence, LayoutGroup, motion } from "framer-motion";
+import { useRef } from "react";
+import { useAtom } from "jotai";
+import { VARIANTS } from "../motion";
+import { Icon } from "../ui/Icon";
+import { ResizeHandle } from "../ui/ResizeHandle";
+import { ListingView } from "../ListingView";
+import { useFolderListing } from "../router";
+import { shortenHome } from "../format";
+import { SIDEBAR_MAX_WIDTH, SIDEBAR_MIN_WIDTH, sidebarWidthAtom } from "../state";
+
+const DOCKED_CLASS =
+	"shrink-0 sticky top-topbar h-[calc(100vh-var(--topbar-height))] border-r border-border-subtle";
+
+function clampWidth(px: number): number {
+	return Math.min(SIDEBAR_MAX_WIDTH, Math.max(SIDEBAR_MIN_WIDTH, Math.round(px)));
+}
+
+/** "/a/b.md" -> "/a/"; "/x.md" -> "/"; a path already ending in "/" is unchanged. */
+function folderOf(path: string): string {
+	if (path.endsWith("/")) return path;
+	const lastSlash = path.lastIndexOf("/");
+	return path.slice(0, lastSlash + 1);
+}
+
+function SidebarBody({
+	rootDir,
+	activePath,
+	docCount,
+	singleRoot,
+	layoutGroupId,
+}: {
+	rootDir: string;
+	activePath: string;
+	docCount: number;
+	singleRoot: boolean;
+	layoutGroupId: string;
+}) {
+	// The roots home page has no path of its own (the mobile drawer can still
+	// open there); skip the listing rather than fetch "".
+	const folder = activePath ? folderOf(activePath) : "";
+	const { entries, error } = useFolderListing(folder);
+
+	return (
+		<>
+			{/* Plain <a>: the router's global click delegation handles navigation. */}
+			<a
+				href={rootDir ? `${rootDir}/` : "/"}
+				title={rootDir}
+				className="mb-1 flex items-center gap-1.5 rounded-md px-2 py-1 font-mono text-[length:var(--size-2xs)] text-text-subtle no-underline hover:bg-surface-hover hover:text-text-heading"
+			>
+				<Icon name="folder-open" size={13} className="shrink-0" />
+				<span className="truncate">{rootDir ? shortenHome(rootDir) : "mdxserve"}</span>
+			</a>
+			{!folder ? null : entries ? (
+				// The desktop column and mobile drawer can both be mounted, and both
+				// contain a row with layoutId="sidebar-active", so each gets its own
+				// namespace here.
+				<LayoutGroup id={layoutGroupId}>
+					<ListingView
+						route={{ path: folder, rootDir, entries }}
+						mode="sidebar"
+						activePath={activePath}
+						singleRoot={singleRoot}
+					/>
+				</LayoutGroup>
+			) : error ? (
+				<p className="px-2 text-[13px] text-text-subtle">Couldn't load this folder.</p>
+			) : null}
+			<div className="mt-4 flex items-center gap-2 border-t border-border-subtle px-2 pt-3 text-[13px] leading-normal font-medium text-text-subtle">
+				<span className="h-1.5 w-1.5 shrink-0 rounded-full bg-teal-400" />
+				Watching {docCount} {docCount === 1 ? "file" : "files"}
+			</div>
+		</>
+	);
+}
+
+export function Sidebar({
+	rootDir,
+	activePath,
+	docCount,
+	singleRoot,
+	desktopOpen,
+	mobileOpen,
+	onCloseMobile,
+}: {
+	rootDir: string;
+	activePath: string;
+	docCount: number;
+	singleRoot: boolean;
+	desktopOpen: boolean;
+	mobileOpen: boolean;
+	onCloseMobile: () => void;
+}) {
+	const [width, setWidth] = useAtom(sidebarWidthAtom);
+	const asideRef = useRef<HTMLDivElement>(null);
+
+	return (
+		<>
+			{/* Mobile overlay: fixed drawer + scrim, closed by default. */}
+			<AnimatePresence>
+				{mobileOpen ? (
+					<motion.div
+						key="sidebar-scrim"
+						data-print-hide
+						{...VARIANTS.scrim}
+						onClick={onCloseMobile}
+						className="fixed inset-0 z-[var(--z-scrim)] bg-[var(--scrim)] md:hidden"
+					/>
+				) : null}
+			</AnimatePresence>
+			<AnimatePresence>
+				{mobileOpen ? (
+					<motion.aside
+						key="sidebar-panel"
+						data-print-hide
+						{...VARIANTS.pop}
+						// Rows are plain links handled by the router, and tapping the already
+						// active doc never changes the route, so close on any link tap here.
+						onClick={(event) => {
+							if ((event.target as HTMLElement).closest("a[href]")) onCloseMobile();
+						}}
+						className={
+							"fixed inset-y-0 left-0 z-[var(--z-modal)] overflow-y-auto border-r border-border-subtle bg-surface-raised px-3 py-6 shadow-lg md:hidden w-sidebar"
+						}
+					>
+						<SidebarBody
+							rootDir={rootDir}
+							activePath={activePath}
+							docCount={docCount}
+							singleRoot={singleRoot}
+							layoutGroupId="sidebar-mobile"
+						/>
+					</motion.aside>
+				) : null}
+			</AnimatePresence>
+
+			{/* Desktop docked column. */}
+			{desktopOpen ? (
+				<aside
+					ref={asideRef}
+					data-print-hide
+					className={"relative hidden md:block " + DOCKED_CLASS}
+					style={{ width: clampWidth(width) }}
+				>
+					<div className="h-full overflow-y-auto px-3 py-6">
+						<SidebarBody
+							rootDir={rootDir}
+							activePath={activePath}
+							docCount={docCount}
+							singleRoot={singleRoot}
+							layoutGroupId="sidebar-desktop"
+						/>
+					</div>
+					{/* Sibling of the scroller, not inside it, so overflow-y-auto can't clip it. */}
+					<ResizeHandle
+						side="right"
+						anchored
+						container={asideRef}
+						onResize={setWidth}
+						label="Resize sidebar"
+						minWidth={SIDEBAR_MIN_WIDTH}
+						maxWidth={SIDEBAR_MAX_WIDTH}
+					/>
+				</aside>
+			) : null}
+		</>
+	);
+}

package/client/shell/StandaloneShell.tsx

@@ -0,0 +1,65 @@
+import { motion } from "framer-motion";
+import { useAtomValue } from "jotai";
+import { useCallback, useRef, useState } from "react";
+import { DocView } from "../DocView";
+import { fadeRise } from "../motion";
+import { useTheme } from "../theme";
+import { docModuleCache } from "../doc-module-cache";
+import { docWidthAtom } from "../state";
+import { Footer } from "./Footer";
+import { TocRail } from "./TocRail";
+import { TopBar } from "./TopBar";
+import { useContentWidth, useDocMaxWidth } from "./use-doc-width";
+import type { StandaloneMeta } from "../standalone-entry";
+
+/**
+ * The shell rendered by a `mdxserve export` output: one doc, no server. A
+ * pared-down `AppShell` — same width spring, resize handles, TOC rail, and
+ * enter animation, but no sidebar, search, breadcrumb, prev/next, or route
+ * transitions (there is only ever one route, baked in at build time).
+ */
+export function StandaloneShell({ meta }: { meta: StandaloneMeta }) {
+	const { theme, toggle } = useTheme();
+	const [tocVersion, setTocVersion] = useState(0);
+	const docWidth = useAtomValue(docWidthAtom);
+	const contentRef = useRef<HTMLDivElement>(null);
+	const contentWidth = useContentWidth(contentRef);
+	const docMaxWidth = useDocMaxWidth(contentWidth, docWidth);
+
+	// Mirrors AppShell's bumpTocVersion: re-scan headings once the article is
+	// on the page, and honour a #hash the browser jumped past before it existed.
+	const bumpTocVersion = useCallback(() => {
+		setTocVersion((version) => version + 1);
+		const hash = window.location.hash.slice(1);
+		if (hash) {
+			document
+				.getElementById(decodeURIComponent(hash))
+				?.scrollIntoView({ block: "start", behavior: "instant" });
+		}
+	}, []);
+
+	return (
+		<div className="min-h-screen bg-surface-page">
+			<TopBar theme={theme} onToggleTheme={toggle} hostLabel={meta.label} />
+			<main className="flex flex-1 min-w-0 px-8 pt-10 pb-24">
+				<div ref={contentRef} data-content-area className="flex flex-1 min-w-0 justify-center">
+					<motion.div
+						variants={fadeRise}
+						initial="initial"
+						animate="enter"
+						className={docMaxWidth ? "w-full" : "w-full max-w-prose"}
+						style={docMaxWidth ? { maxWidth: docMaxWidth } : undefined}
+					>
+						<DocView
+							path={meta.path}
+							module={docModuleCache.get(meta.path)}
+							onRendered={bumpTocVersion}
+						/>
+						<Footer label={meta.label} mtime={meta.mtime} />
+					</motion.div>
+				</div>
+				<TocRail path={meta.path} version={tocVersion} />
+			</main>
+		</div>
+	);
+}