@karimsa/mdxserve 0.2.0 → 0.4.0

package/README.md

@@ -24,9 +24,9 @@ updates. Write JSX in an `.mdx` file and it renders too.
 
 ![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.
+It works with folders of Markdown that already exist: notes, a `docs/` directory, or plan
+files an AI agent wrote. For local use, there is no build step or config file: run it,
+open the URL, and read. Use `--permissions restricted` to publish one folder as a read-only site.
 
 ## Install
 
@@ -41,6 +41,11 @@ mdxserve setup      # optional: installs the writing skill for Claude Code and C
 (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.
 
+Interactive commands check for updates in the background at most once a day and show
+cached update notices on startup. Updates are never installed automatically. Disable
+checks with `--no-update-notifier` or `NO_UPDATE_NOTIFIER=1`. CI, noninteractive commands,
+and `--json` output stay quiet.
+
 ## Quick start
 
 ```bash
@@ -60,14 +65,59 @@ 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.
+Roots persist in `~/.mdxserve/config.json` (`$MDXSERVE_HOME/config.json` when set).
+`mdxserve serve` restores them on restart; `-w` adds folders to the saved list.
+You can also edit the file directly, including while the server is stopped:
+
+```json
+{
+	"roots": ["~/notes", "~/work/docs"]
+}
+```
+
+The running server automatically reloads edits, updating open browsers and document access.
+Relative paths resolve against the config directory; `~` resolves against your home directory.
+Use `"roots": []` to unmount everything. Invalid JSON, missing directories, and invalid root
+combinations leave the last working set active and log an error; fix the file to resume
+reloading. Deleting the config while running also preserves the last working set until the
+file is restored. An invalid config at startup reports an error. Root commands save changes
+atomically and preserve unrelated settings. SQLite records only the live server's status;
+the JSON file is the source of truth for which roots should exist.
+
+| 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; determines default permission mode     |
+| `--dangerous-allow-network` | off             | Authorize full permissions on a non-loopback interface    |
+| `--permissions <mode>`      | interface-based | `full` on loopback, `restricted` on other interfaces      |
+
+## Hosting a public reader
+
+Permission mode defaults to `full` on loopback and `restricted` on other interfaces.
+The effective mode is printed at startup. Use `--permissions restricted` to select the
+public reader restrictions explicitly, including behind a proxy connected over loopback:
+
+```bash
+MDXSERVE_HOME=/tmp/mdxserve-public mdxserve serve --permissions restricted -w ./site --host 0.0.0.0 -p "${PORT:-4040}"
+```
 
-| 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       |
+Restricted mode requires one `-w` directory. It ignores saved roots
+and config changes. All HTTP mutations are denied, including editing, Trash, root changes,
+exports, and diagram agents, even when a reverse proxy connects over loopback. The reader,
+navigation, and search remain available. A restricted instance will not reuse another server
+under the same `MDXSERVE_HOME`; give it its own directory.
+
+Treat every file in `./site` as public. Visitors can fetch MDX source and visible assets,
+including imported CSS and JSX. Vite also serves the mdxserve client and dependency modules
+needed by the page. Hidden files, links to hidden targets, and links outside the served root
+are blocked; links to visible files inside the root still work.
+Run the server with a read-only site directory and no agent credentials. At the public proxy,
+limit requests per client and concurrent requests to bound repeated Vite compilation and
+search work.
+Full permissions on a non-loopback interface require both `--permissions full` and
+`--dangerous-allow-network`. The dangerous flag alone leaves the default restricted mode
+in place. Use full network access only on a trusted network.
 
 ## Writing docs
 

package/client/CodeBlock.tsx

@@ -1,3 +1,4 @@
+import { DiagramEditContext } from "./diagrams/edit-context";
 import {
 	Children,
 	createContext,
@@ -241,6 +242,7 @@ function CodeFrame({
 }) {
 	const containerRef = useRef<HTMLDivElement>(null);
 	const isMermaid = language === "mermaid";
+	const editDiagram = useContext(DiagramEditContext);
 	const [view, setView] = useState<"diagram" | "code">("diagram");
 	const [source, setSource] = useState<string | null>(null);
 	const label = title ?? language;
@@ -294,6 +296,7 @@ function CodeFrame({
 	return (
 		<div
 			ref={containerRef}
+			data-mermaid-editable={isMermaid ? "" : undefined}
 			className="overflow-hidden rounded-lg border border-code-border bg-code-bg"
 		>
 			<CodeFrameHeader
@@ -302,6 +305,27 @@ function CodeFrame({
 					<>
 						{isMermaid ? <ViewToggle view={view} onChange={setView} toggleId={toggleId} /> : null}
 						{showDiagram ? directionMenu : null}
+						{isMermaid && editDiagram && (
+							<button
+								type="button"
+								aria-label="Edit diagram"
+								data-print-hide
+								className="inline-flex items-center gap-1.5 text-[length:var(--size-xs)] text-text-subtle hover:text-text-heading"
+								onClick={() => {
+									const frame = containerRef.current;
+									const section = frame?.closest("[data-md-section]");
+									if (!frame || !section) return;
+									const index = [...section.querySelectorAll("[data-mermaid-editable]")].indexOf(
+										frame,
+									);
+									if (index >= 0) editDiagram({ index, source: getCopyText() });
+								}}
+							>
+								<Icon name="pencil" size={12} />
+								Edit
+							</button>
+						)}
+
 						<CopyButton getText={getCopyText} />
 					</>
 				}

package/client/DocView.tsx

@@ -5,7 +5,13 @@ import { ErrorBox } from "./ErrorBox";
 import { RenderErrorBoundary } from "./RenderErrorBoundary";
 import type { DocModuleState } from "./doc-module-cache";
 import { ResizeHandle } from "./ui/ResizeHandle";
-import { DOC_MAX_WIDTH, DOC_MIN_WIDTH, docWidthAtom, openSectionAtom } from "./state";
+import {
+	contentLayoutAtom,
+	DOC_MAX_WIDTH,
+	DOC_MIN_WIDTH,
+	docWidthAtom,
+	openSectionAtom,
+} from "./state";
 
 // Each Component a re-import produces (including an HMR re-import after a
 // fix) is a distinct function identity, so this assigns it a stable, unique
@@ -45,6 +51,7 @@ export function DocView({
 	onRendered?: () => void;
 }) {
 	const cached = module;
+	const fullWidth = useAtomValue(contentLayoutAtom) === "full-width";
 	const setWidth = useSetAtom(docWidthAtom);
 	// While a section is being edited the page width is pinned: a drag would
 	// reflow the editor under the caret, and the handles' hover strips sit
@@ -75,7 +82,7 @@ export function DocView({
 	const Content = cached.Component;
 	return (
 		<div ref={container} className="relative">
-			{!editing && (
+			{!editing && !fullWidth && (
 				<>
 					<ResizeHandle
 						side="left"

package/client/ListingView.tsx

@@ -1,5 +1,5 @@
 import { AnimatePresence, motion } from "framer-motion";
-import { useAtom, useSetAtom } from "jotai";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useMutation } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
 import { queryClient, trpc } from "./api";
@@ -9,10 +9,11 @@ import { Icon } from "./ui/Icon";
 import { ResizeHandle } from "./ui/ResizeHandle";
 import { ConfirmDeleteDialog } from "./ui/ConfirmDeleteDialog";
 import { pushToast } from "./ui/Toast";
-import type { ListingEntry } from "./router";
+import { shellInfo, type ListingEntry } from "./router";
 import Button from "./builtins/Button";
 import Dropdown from "./builtins/Dropdown";
 import {
+	contentLayoutAtom,
 	LISTING_MAX_WIDTH,
 	LISTING_MIN_WIDTH,
 	listingSortAtom,
@@ -371,6 +372,7 @@ export function ListingView({
 }) {
 	const { path, rootDir, entries } = route;
 	const sidebar = mode === "sidebar";
+	const canDelete = shellInfo.permissions !== "restricted" && !sidebar;
 	const atRootTop = path === `${rootDir}/`;
 	const segments = path.split("/").filter(Boolean);
 	const parentSegments = segments.slice(0, -1);
@@ -389,6 +391,7 @@ export function ListingView({
 		[sorted, sidebar],
 	);
 	const setWidth = useSetAtom(listingWidthAtom);
+	const fullWidth = useAtomValue(contentLayoutAtom) === "full-width";
 	const container = useRef<HTMLDivElement>(null);
 
 	const [selectedNames, setSelectedNames] = useState<Set<string>>(new Set());
@@ -436,14 +439,14 @@ export function ListingView({
 	// consumed it, or the confirm dialog is up (it handles its own Escape).
 	// Sidebar mode has no selection to clear, so skip wiring the listener.
 	useEffect(() => {
-		if (sidebar) return;
+		if (!canDelete) return;
 		function onKeyDown(event: globalThis.KeyboardEvent) {
 			if (event.defaultPrevented || confirmOpen) return;
 			if (event.key === "Escape" && selectionActive) setSelectedNames(new Set());
 		}
 		document.addEventListener("keydown", onKeyDown);
 		return () => document.removeEventListener("keydown", onKeyDown);
-	}, [sidebar, confirmOpen, selectionActive]);
+	}, [canDelete, confirmOpen, selectionActive]);
 
 	const trashMutation = useMutation(
 		trpc.moveDocsToTrash.mutationOptions({
@@ -455,6 +458,7 @@ export function ListingView({
 	// `pending` and fire a duplicate request before React re-renders.
 	const pendingRef = useRef(false);
 	const handleConfirm = async () => {
+		if (!canDelete) return;
 		if (pendingRef.current) return;
 		pendingRef.current = true;
 		setPending(true);
@@ -497,7 +501,7 @@ export function ListingView({
 
 	return (
 		<div ref={container} className="relative">
-			{sidebar ? null : (
+			{sidebar || fullWidth ? null : (
 				<>
 					<ResizeHandle
 						side="left"
@@ -531,8 +535,8 @@ export function ListingView({
 			) : (
 				<div className="mb-2 flex items-center justify-between gap-2">
 					<div data-print-hide className="flex items-center gap-2">
-						<SelectMenu fileEntries={fileEntries} onSelect={setSelectedNames} />
-						{selectionActive ? (
+						{canDelete && <SelectMenu fileEntries={fileEntries} onSelect={setSelectedNames} />}
+						{canDelete && selectionActive ? (
 							<>
 								<span className="font-sans font-medium leading-normal text-[length:var(--size-sm)] text-text-subtle tabular-nums">
 									{selected.length} selected
@@ -608,7 +612,7 @@ export function ListingView({
 							/>
 						);
 					}
-					const selection = sidebar
+					const selection = !canDelete
 						? {}
 						: {
 								selectable: true,
@@ -647,7 +651,7 @@ export function ListingView({
 					);
 				})}
 			</motion.div>
-			{sidebar ? null : (
+			{canDelete ? (
 				<ConfirmDeleteDialog
 					open={confirmOpen}
 					files={selected}
@@ -657,7 +661,7 @@ export function ListingView({
 					}}
 					onConfirm={handleConfirm}
 				/>
-			)}
+			) : null}
 		</div>
 	);
 }

package/client/MarkdownTable.tsx

@@ -0,0 +1,190 @@
+import {
+	Children,
+	isValidElement,
+	useId,
+	type CSSProperties,
+	type ReactNode,
+	type TableHTMLAttributes,
+} from "react";
+import DataTable from "./builtins/DataTable";
+import { inferColumn, parseBound, type Column, type Row } from "./data-table/model";
+
+function elements(children: ReactNode) {
+	return Children.toArray(children).filter(
+		isValidElement<{
+			children?: ReactNode;
+			align?: string;
+			style?: CSSProperties;
+			rowSpan?: number;
+			colSpan?: number;
+		}>,
+	);
+}
+
+function text(children: ReactNode): string {
+	return Children.toArray(children)
+		.map((child) =>
+			isValidElement<{ children?: ReactNode }>(child)
+				? text(child.props.children)
+				: typeof child === "string" || typeof child === "number"
+					? String(child)
+					: "",
+		)
+		.join("");
+}
+
+type TableElement = ReturnType<typeof elements>[number];
+
+function isElementOnly(children: ReactNode): boolean {
+	return Children.toArray(children).every(
+		(child) => isValidElement(child) || (typeof child === "string" && !child.trim()),
+	);
+}
+
+/** Rebuilt descendants only preserve children and the column-wide GFM alignment. */
+function hasUnsupportedProps(element: TableElement, cell = false): boolean {
+	return Object.keys(element.props).some((key) => {
+		if (key === "children" || (cell && key === "align")) return false;
+		if (cell && key === "style")
+			return Object.keys(element.props.style ?? {}).some((property) => property !== "textAlign");
+		return true;
+	});
+}
+
+function rectangularCells(row: TableElement, cellType: "th" | "td"): TableElement[] | undefined {
+	if (row.type !== "tr" || hasUnsupportedProps(row) || !isElementOnly(row.props.children))
+		return undefined;
+	const cells = elements(row.props.children);
+	if (
+		cells.some(
+			(cell) =>
+				cell.type !== cellType ||
+				hasUnsupportedProps(cell, true) ||
+				(cell.props.rowSpan !== undefined && cell.props.rowSpan !== 1) ||
+				(cell.props.colSpan !== undefined && cell.props.colSpan !== 1),
+		)
+	)
+		return undefined;
+	return cells;
+}
+
+/** Only reconstruct a single rectangular header/body; preserve richer native structures intact. */
+function tableStructure(children: ReactNode) {
+	if (!isElementOnly(children)) return undefined;
+	const sections = elements(children);
+	if (sections.length !== 2 || sections[0].type !== "thead" || sections[1].type !== "tbody")
+		return undefined;
+	if (
+		sections.some(
+			(section) => hasUnsupportedProps(section) || !isElementOnly(section.props.children),
+		)
+	)
+		return undefined;
+
+	const headerRows = elements(sections[0].props.children);
+	if (headerRows.length !== 1) return undefined;
+	const headers = rectangularCells(headerRows[0], "th");
+	if (!headers?.length) return undefined;
+
+	const cells: TableElement[][] = [];
+	for (const row of elements(sections[1].props.children)) {
+		const rowCells = rectangularCells(row, "td");
+		if (!rowCells || rowCells.length !== headers.length) return undefined;
+		if (
+			rowCells.some(
+				(cell, index) =>
+					(cell.props.style?.textAlign ?? cell.props.align) !==
+					(headers[index].props.style?.textAlign ?? headers[index].props.align),
+			)
+		)
+			return undefined;
+		cells.push(rowCells);
+	}
+	return { headers, cells };
+}
+
+function prepareMarkdownTable(children: ReactNode) {
+	const structure = tableStructure(children);
+	if (!structure) return undefined;
+	const { headers, cells } = structure;
+	const columns: Column[] = headers.map((cell, index) => {
+		const align = cell.props.style?.textAlign ?? cell.props.align;
+		const alignment =
+			align === "left" || align === "center" || align === "right" ? align : undefined;
+		const column = inferColumn(
+			`column-${index}`,
+			text(cell.props.children) || `Column ${index + 1}`,
+			cells.map((row) => text(row[index]?.props.children)),
+		);
+		// Converting units must never erase a link or an inline component.
+		if (
+			(column.type === "time" || column.type === "bytes") &&
+			cells.some((row) => elements(row[index]?.props.children).length > 0)
+		)
+			return { key: column.key, label: column.label, type: "text", align: alignment };
+		return { ...column, align: alignment };
+	});
+	const data: Row[] = cells.map((row) =>
+		Object.fromEntries(
+			columns.map((column, index) => {
+				const value = text(row[index]?.props.children).trim();
+				return [
+					column.key,
+					column.type === "text"
+						? value
+						: value === "" || value === "—"
+							? null
+							: (parseBound(value, column) ?? null),
+				];
+			}),
+		),
+	);
+
+	return { columns, data, cells, headers };
+}
+
+function renderMarkdownCell(
+	table: NonNullable<ReturnType<typeof prepareMarkdownTable>>,
+	row: number,
+	key: string,
+) {
+	const index = Number(key.slice(7));
+	const column = table.columns[index];
+
+	// Unit columns use DataTable's shared-unit formatter; other cells retain their original markup.
+	if (column.type === "time" || column.type === "bytes") return undefined;
+	return table.cells[row][index]?.props.children;
+}
+
+export function MarkdownTable({
+	children,
+	id,
+	"data-table-persist": persist,
+	...tableProps
+}: TableHTMLAttributes<HTMLTableElement> & { "data-table-persist"?: string }) {
+	const fallbackId = useId();
+	const table = prepareMarkdownTable(children);
+
+	if (!table)
+		return (
+			<div className="data-table">
+				<div className="data-table-scroll">
+					<table {...tableProps} id={id}>
+						{children}
+					</table>
+				</div>
+			</div>
+		);
+
+	return (
+		<DataTable
+			id={id ?? `markdown-${fallbackId}`}
+			columns={table.columns}
+			data={table.data}
+			persistState={Boolean(id) && persist !== "false"}
+			tableProps={{ ...tableProps, id }}
+			renderHeader={(key) => table.headers[Number(key.slice(7))]?.props.children}
+			renderCell={(row, key) => renderMarkdownCell(table, row, key)}
+		/>
+	);
+}

package/client/MdSection.tsx

@@ -1,3 +1,5 @@
+import { AnimatePresence } from "framer-motion";
+import { DiagramEditContext, type ExistingDiagram } from "./diagrams/edit-context";
 import {
 	lazy,
 	startTransition,
@@ -12,6 +14,7 @@ import { useAtom } from "jotai";
 import { trpcClient } from "./api";
 import { DocContext } from "./DocContext";
 import { openSectionAtom } from "./state";
+import { shellInfo } from "./router";
 import { IconButton } from "./ui/IconButton";
 import { pushToast } from "./ui/Toast";
 
@@ -23,6 +26,9 @@ import { pushToast } from "./ui/Toast";
 // when React commits the "edit" branch below, which SSR never reaches.
 const loadEditor = () => import("./MdSectionEditor");
 const MdSectionEditor = lazy(loadEditor);
+const DiagramEditDialog = lazy(() =>
+	import("./diagrams/EditDialog").then((module) => ({ default: module.DiagramEditDialog })),
+);
 
 // Warm the editor chunk as soon as a pointer lands on any section, so by the
 // time the user has double-clicked or reached the pencil the lazy import is
@@ -94,7 +100,8 @@ function Section({
 	endLine: number;
 	children: ReactNode;
 }) {
-	const [mode, setMode] = useState<"read" | "loading" | "edit">("read");
+	const [mode, setMode] = useState<"read" | "loading" | "edit" | "diagram">("read");
+	const [initialDiagram, setInitialDiagram] = useState<ExistingDiagram | undefined>();
 	const [source, setSource] = useState("");
 	const [version, setVersion] = useState("");
 	const [openSection, setOpenSection] = useAtom(openSectionAtom);
@@ -120,9 +127,11 @@ function Section({
 		};
 	}, [key, setOpenSection]);
 
-	async function startEdit() {
+	async function startEdit(target?: ExistingDiagram) {
+		if (shellInfo.permissions === "restricted") return;
 		// Double-click and the pencil can both fire while a fetch is in flight.
 		if (mode !== "read") return;
+		setInitialDiagram(target);
 		setOpenSection(key);
 		setMode("loading");
 		try {
@@ -145,7 +154,7 @@ function Section({
 			// one go — instead of swapping in the Suspense fallback first and
 			// then the editor, which read as a flash.
 			startTransition(() => {
-				setMode((current) => (current === "loading" ? "edit" : current));
+				setMode((current) => (current === "loading" ? (target ? "diagram" : "edit") : current));
 			});
 		} catch {
 			pushToast({ tone: "danger", text: "Couldn't open section for editing" });
@@ -202,6 +211,7 @@ function Section({
 	// word inside a code block, and svg-pan-zoom's double-click zoom on a
 	// mermaid diagram (client/Mermaid.tsx `dblClickZoomEnabled`).
 	function onDoubleClick(event: MouseEvent<HTMLDivElement>) {
+		if (shellInfo.permissions === "restricted") return;
 		const target = event.target as Element | null;
 		if (target?.closest("a, button, input, select, textarea, summary, pre, svg")) return;
 		event.preventDefault();
@@ -209,26 +219,51 @@ function Section({
 	}
 
 	return (
-		<div
-			className="mdx-section group"
-			data-md-section={index}
-			onDoubleClick={onDoubleClick}
-			onPointerEnter={preloadEditor}
+		<DiagramEditContext.Provider
+			value={
+				shellInfo.permissions !== "restricted" && mode === "read"
+					? (target) => void startEdit(target)
+					: null
+			}
 		>
-			{children}
-			{/* Floats over the section's top-right corner rather than in the left
+			<AnimatePresence>
+				{mode === "diagram" && initialDiagram && (
+					<Suspense fallback={null}>
+						<DiagramEditDialog
+							source={source}
+							target={initialDiagram}
+							path={path}
+							version={version}
+							startLine={startLine}
+							endLine={endLine}
+							onClose={finishEdit}
+						/>
+					</Suspense>
+				)}
+			</AnimatePresence>
+			<div
+				className="mdx-section group"
+				data-md-section={index}
+				onDoubleClick={shellInfo.permissions === "restricted" ? undefined : onDoubleClick}
+				onPointerEnter={shellInfo.permissions === "restricted" ? undefined : preloadEditor}
+			>
+				{children}
+				{/* Floats over the section's top-right corner rather than in the left
 			    gutter, which is where DocView's left ResizeHandle lives — the two
 			    hover affordances were fighting for the same strip of pixels. */}
-			<IconButton
-				icon="pencil"
-				label="Edit section"
-				size="sm"
-				variant="outline"
-				data-print-hide
-				disabled={mode === "loading"}
-				onClick={startEdit}
-				className="absolute -top-3 right-0 z-20 opacity-0 shadow-sm transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
-			/>
-		</div>
+				{shellInfo.permissions !== "restricted" && (
+					<IconButton
+						icon="pencil"
+						label="Edit section"
+						size="sm"
+						variant="outline"
+						data-print-hide
+						disabled={mode === "loading"}
+						onClick={() => void startEdit()}
+						className="mdx-section-edit absolute -top-3 right-0 z-20 opacity-0 shadow-sm transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
+					/>
+				)}
+			</div>
+		</DiagramEditContext.Provider>
 	);
 }