@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/diagrams/Preferences.tsx

@@ -0,0 +1,213 @@
+import { useEffect, useState } from "react";
+import ChevronDown from "lucide-react/dist/esm/icons/chevron-down.mjs";
+import { Settings } from "../Settings";
+import { trpcClient } from "../api";
+export type AgentChoice = "codex" | "claude" | "disabled";
+export function DiagramPreferences({
+	onClose,
+	canEditDiagrams = true,
+}: {
+	onClose: () => void;
+	canEditDiagrams?: boolean;
+}) {
+	return canEditDiagrams ? <DiagramSettings onClose={onClose} /> : <Settings onClose={onClose} />;
+}
+
+function DiagramSettings({ onClose }: { onClose: () => void }) {
+	const [agent, setAgent] = useState<AgentChoice>("disabled");
+	const [models, setModels] = useState({ codex: "", claude: "" });
+	const [catalog, setCatalog] = useState<{ id: string; label: string }[]>([]);
+	const [loadingModels, setLoadingModels] = useState(false);
+	const [modelError, setModelError] = useState("");
+	const [refreshModels, setRefreshModels] = useState(0);
+	const [statuses, setStatuses] = useState("Agents haven’t been checked yet.");
+	const [error, setError] = useState("");
+	const [pending, setPending] = useState(true);
+	const [checking, setChecking] = useState(false);
+	const [loaded, setLoaded] = useState(false);
+	useEffect(() => {
+		void trpcClient.getDiagramPreferences
+			.query({})
+			.then((result) => {
+				setAgent(result.agent);
+				setModels(result.models);
+				setLoaded(true);
+			})
+			.catch((failure) => setError(failure.message))
+			.finally(() => setPending(false));
+	}, []);
+	useEffect(() => {
+		let obsolete = false;
+		setCatalog([]);
+		setModelError("");
+		if (!loaded || agent === "disabled") {
+			setLoadingModels(false);
+			return;
+		}
+		setLoadingModels(true);
+		void trpcClient.listDiagramModels
+			.mutate({ provider: agent })
+			.then((result) => {
+				if (!obsolete) setCatalog(result);
+			})
+			.catch(() => {
+				if (!obsolete) setModelError("Couldn’t load models. Your saved choice is unchanged.");
+			})
+			.finally(() => {
+				if (!obsolete) setLoadingModels(false);
+			});
+		return () => {
+			obsolete = true;
+		};
+	}, [agent, loaded, refreshModels]);
+	async function save(nextAgent: AgentChoice, nextModels = models) {
+		const previousAgent = agent;
+		const previousModels = models;
+		setAgent(nextAgent);
+		setModels(nextModels);
+		setPending(true);
+		setError("");
+		try {
+			await trpcClient.setDiagramPreferences.mutate({ agent: nextAgent, models: nextModels });
+			window.dispatchEvent(new Event("mdxserve-diagram-preferences"));
+		} catch {
+			setAgent(previousAgent);
+			setModels(previousModels);
+			setError("Couldn’t save settings. Your previous settings are unchanged. Try again.");
+		} finally {
+			setPending(false);
+		}
+	}
+
+	return (
+		<Settings
+			onClose={onClose}
+			saving={(loaded && pending) || checking}
+			status={
+				error ? (
+					<p role="alert" className="diagram-error">
+						{error}
+					</p>
+				) : (
+					<span role="status">
+						{pending ? (loaded ? "Saving…" : "Loading settings…") : "Settings save automatically."}
+					</span>
+				)
+			}
+			diagrams={
+				<section>
+					<h3>Diagram generation</h3>
+					<p>Turn descriptions and images into editable Mermaid.</p>
+					<label className="diagram-setting-row" htmlFor="diagram-agent">
+						<span>
+							<strong>Default agent</strong>
+							<small>Use an installed, signed-in CLI.</small>
+						</span>
+						<span className="diagram-agent-select">
+							<select
+								id="diagram-agent"
+								value={agent}
+								onChange={(event) => void save(event.target.value as AgentChoice)}
+								disabled={!loaded || pending || checking}
+							>
+								<option value="codex">Codex</option>
+								<option value="claude">Claude Code</option>
+								<option value="disabled">Disabled</option>
+							</select>
+							<ChevronDown size={14} aria-hidden="true" />
+						</span>
+					</label>
+					<p className="diagram-setting-note">
+						Auto detect selects an installed, signed-in agent for every conversion.
+					</p>
+					{agent !== "disabled" && (
+						<>
+							<label className="diagram-setting-row" htmlFor="diagram-model">
+								<span>
+									<strong>Model</strong>
+									<small>{agent === "codex" ? "Codex" : "Claude Code"} model for diagrams.</small>
+								</span>
+								<span className="diagram-agent-select diagram-model-select">
+									<select
+										id="diagram-model"
+										aria-label="Model"
+										value={models[agent]}
+										disabled={!loaded || loadingModels || pending || checking}
+										onChange={(event) =>
+											void save(agent, { ...models, [agent]: event.target.value })
+										}
+									>
+										{!catalog.some((model) => model.id === models[agent]) && (
+											<option value={models[agent]}>
+												{models[agent]}
+												{loadingModels ? "" : " (saved)"}
+											</option>
+										)}
+										{catalog.map((model) => (
+											<option key={model.id} value={model.id}>
+												{model.label}
+											</option>
+										))}
+									</select>
+									<ChevronDown size={14} aria-hidden="true" />
+								</span>
+							</label>
+							<div className="diagram-model-status">
+								<small role="status">
+									{loadingModels
+										? "Loading models from CLI…"
+										: modelError || "Models from your installed CLI."}
+								</small>
+								<button
+									type="button"
+									disabled={loadingModels}
+									onClick={() => setRefreshModels((value) => value + 1)}
+								>
+									Refresh models
+								</button>
+							</div>
+						</>
+					)}
+					<div className="diagram-agent-status">
+						<span role="status">{statuses}</span>
+						<button
+							type="button"
+							disabled={checking || pending || !loaded}
+							onClick={async () => {
+								setChecking(true);
+								setStatuses("Checking agents…");
+								try {
+									const result = await trpcClient.probeDiagramAgents.mutate({});
+									const ready = result.filter((status) => status.state === "ready");
+									await save(
+										ready.find((status) => status.provider === agent)?.provider ??
+											ready[0]?.provider ??
+											"disabled",
+									);
+									setStatuses(
+										result
+											.map(
+												(status) =>
+													`${status.provider === "codex" ? "Codex" : "Claude Code"}: ${status.state}`,
+											)
+											.join(" · "),
+									);
+								} catch {
+									setStatuses("Could not check agents");
+								} finally {
+									setChecking(false);
+								}
+							}}
+						>
+							Auto detect
+						</button>
+					</div>
+					<p className="diagram-settings-disclosure">
+						Text and images are sent to the selected provider using your account. Disabled stops
+						conversion; existing diagrams still render.
+					</p>
+				</section>
+			}
+		/>
+	);
+}

package/client/diagrams/edit-block.ts

@@ -0,0 +1,93 @@
+import { comparableSource } from "./source";
+import { Extension, type Editor, type Range } from "@tiptap/core";
+import { Plugin } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import { closeHistory } from "@tiptap/pm/history";
+import type { ExistingDiagram } from "./edit-context";
+export type DiagramEditTarget = { range: Range; source: string };
+export function findDiagram(editor: Editor, target: ExistingDiagram): DiagramEditTarget | null {
+	let index = 0;
+	let found: DiagramEditTarget | null = null;
+	editor.state.doc.descendants((node, position) => {
+		if (node.type.name !== "codeBlock" || node.attrs.language !== "mermaid") return;
+		if (
+			index++ === target.index &&
+			comparableSource(node.textContent) === comparableSource(target.source)
+		)
+			found = { range: { from: position, to: position + node.nodeSize }, source: node.textContent };
+	});
+	return found;
+}
+/** Replace exactly the captured block, preserving its attributes and an independent undo step. */
+export function replaceDiagram(editor: Editor, target: DiagramEditTarget, source: string): boolean {
+	if (target.range.from < 0 || target.range.from >= editor.state.doc.content.size) return false;
+	const node = editor.state.doc.nodeAt(target.range.from);
+	if (
+		!node ||
+		node.type.name !== "codeBlock" ||
+		node.attrs.language !== "mermaid" ||
+		node.textContent !== target.source ||
+		target.range.to !== target.range.from + node.nodeSize
+	)
+		return false;
+	editor.view.dispatch(closeHistory(editor.state.tr));
+	const replaced = editor.commands.insertContentAt(target.range, {
+		type: "codeBlock",
+		attrs: node.attrs,
+		content: source ? [{ type: "text", text: source }] : [],
+	});
+	editor.view.dispatch(closeHistory(editor.state.tr));
+	return replaced;
+}
+/** Keep the same edit action available while the section is already in Tiptap. */
+export function mermaidEditButtons(
+	enabled: () => boolean,
+	onEdit: (target: DiagramEditTarget) => void,
+) {
+	return Extension.create({
+		name: "mermaidEditButtons",
+		addProseMirrorPlugins() {
+			return [
+				new Plugin({
+					props: {
+						decorations(state) {
+							if (!enabled()) return DecorationSet.empty;
+							const decorations: Decoration[] = [];
+							state.doc.descendants((node, position) => {
+								if (node.type.name !== "codeBlock" || node.attrs.language !== "mermaid") return;
+								decorations.push(
+									Decoration.widget(
+										position,
+										() => {
+											const button = document.createElement("button");
+											button.type = "button";
+											button.className = "diagram-edit-block";
+											button.textContent = "Edit diagram";
+											button.setAttribute("aria-label", "Edit diagram");
+											// Keep ProseMirror from moving the selection and replacing this widget before click.
+											button.onmousedown = (event) => {
+												event.preventDefault();
+												event.stopPropagation();
+											};
+											button.onclick = (event) => {
+												event.preventDefault();
+												event.stopPropagation();
+												onEdit({
+													range: { from: position, to: position + node.nodeSize },
+													source: node.textContent,
+												});
+											};
+											return button;
+										},
+										{ side: -1 },
+									),
+								);
+							});
+							return DecorationSet.create(state.doc, decorations);
+						},
+					},
+				}),
+			];
+		},
+	});
+}

package/client/diagrams/edit-context.ts

@@ -0,0 +1,4 @@
+import { createContext } from "react";
+export type ExistingDiagram = { index: number; source: string };
+/** Only editable Markdown sections provide this; exports and standalone components do not. */
+export const DiagramEditContext = createContext<((target: ExistingDiagram) => void) | null>(null);

package/client/diagrams/session-id.ts

@@ -0,0 +1,8 @@
+/** getRandomValues works on plain HTTP LAN origins as well as secure contexts. */
+export function sessionId(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	bytes[6] = (bytes[6] & 0x0f) | 0x40;
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+	const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/client/diagrams/slash.ts

@@ -0,0 +1,94 @@
+import { Extension, type Range } from "@tiptap/core";
+import Suggestion from "@tiptap/suggestion";
+import { PluginKey } from "@tiptap/pm/state";
+
+export function mermaidSlash(enabled: () => boolean, onOpen: (range: Range) => void) {
+	return Extension.create({
+		name: "mermaidSlash",
+		addProseMirrorPlugins() {
+			return [
+				Suggestion({
+					editor: this.editor,
+					pluginKey: new PluginKey("mermaidSlash"),
+					char: "/",
+					startOfLine: true,
+					allow: ({ editor, state, range }) =>
+						enabled() &&
+						editor.isEditable &&
+						state.selection.empty &&
+						!state.selection.$from.marks().some((mark) => mark.type.name === "code") &&
+						state.doc.resolve(range.from).parent.type.name === "paragraph" &&
+						state.doc.resolve(range.from).parent.textContent ===
+							state.doc.textBetween(range.from, range.to),
+					items: ({ query }) =>
+						["mermaid", "diagram", "er", "image"].some((term) =>
+							term.startsWith(query.toLowerCase()),
+						)
+							? ["mermaid"]
+							: [],
+					command: ({ range }) => onOpen(range),
+					render: () => {
+						let menu: HTMLDivElement | undefined;
+						let choose: (() => void) | undefined;
+						return {
+							onStart(props) {
+								menu = document.createElement("div");
+								menu.className = "diagram-slash-menu";
+								menu.hidden = props.items.length === 0;
+								menu.setAttribute("role", "listbox");
+								menu.setAttribute("aria-label", "Insert block");
+								const button = document.createElement("button");
+								button.type = "button";
+								button.setAttribute("role", "option");
+								button.setAttribute("aria-selected", "true");
+								button.textContent = "Mermaid diagram";
+								button.onmousedown = (event) => {
+									event.preventDefault();
+									choose?.();
+									menu?.remove();
+									menu = undefined;
+								};
+								menu.append(button);
+								document.body.append(menu);
+								choose = () => props.command("mermaid");
+								const rect = props.clientRect?.();
+								if (rect) {
+									menu.style.left = `${Math.max(8, Math.min(rect.left, window.innerWidth - 260))}px`;
+									menu.style.top = `${Math.min(rect.bottom + 6, window.innerHeight - 70)}px`;
+								}
+							},
+							onUpdate(props) {
+								choose = () => props.command("mermaid");
+								if (menu) menu.hidden = props.items.length === 0;
+							},
+							onKeyDown({ event }) {
+								if (event.key === "Escape") {
+									menu?.remove();
+									menu = undefined;
+									event.preventDefault();
+									event.stopPropagation();
+									return true;
+								}
+								if (menu && !menu.hidden && ["Enter", "ArrowDown", "ArrowUp"].includes(event.key)) {
+									event.preventDefault();
+									event.stopPropagation();
+									if (event.key === "Enter") {
+										choose?.();
+										menu.remove();
+										menu = undefined;
+									}
+									return true;
+								}
+								return false;
+							},
+							onExit() {
+								menu?.remove();
+								menu = undefined;
+							},
+						};
+					},
+				}),
+			];
+		},
+	});
+}

package/client/diagrams/source.ts

@@ -0,0 +1,73 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import type { Code, RootContent } from "mdast";
+import type { ExistingDiagram } from "./edit-context";
+
+// Syntax highlighting pads empty lines for display; those spaces aren't edits.
+export function comparableSource(source: string): string {
+	return source
+		.replace(/\r\n/g, "\n")
+		.replace(/^[\t ]+$/gm, "")
+		.trim();
+}
+
+/** Locate the original fence without round-tripping the surrounding Markdown. */
+export function locateDiagram(markdown: string, target: ExistingDiagram) {
+	const diagrams: Code[] = [];
+	function visit(node: RootContent): void {
+		if (node.type === "code" && node.lang === "mermaid") diagrams.push(node);
+		if ("children" in node) for (const child of node.children) visit(child as RootContent);
+	}
+	for (const node of fromMarkdown(markdown).children) visit(node);
+	const node = diagrams[target.index];
+	const start = node?.position?.start.offset;
+	const end = node?.position?.end.offset;
+	if (
+		!node ||
+		start === undefined ||
+		end === undefined ||
+		comparableSource(node.value) !== comparableSource(target.source)
+	)
+		return null;
+	const original = markdown.slice(start, end);
+	const opening = original.match(/^(`{3,}|~{3,})[^\n]*(?:\n|$)/);
+	if (!opening) return null;
+	const lastBreak = original.lastIndexOf("\n");
+	const lastLine = original.slice(lastBreak + 1);
+	const fence = opening[1];
+	const closeMatch = lastLine.match(/^([\t >]*)(`{3,}|~{3,})[\t ]*$/);
+	const hasClosing =
+		lastBreak >= 0 &&
+		closeMatch &&
+		closeMatch[2][0] === fence[0] &&
+		closeMatch[2].length >= fence.length;
+	// Markdown permits fences terminated by EOF or the end of their container.
+	// Retain container indentation when adding an explicit closing delimiter.
+	const lineStart = markdown.lastIndexOf("\n", start - 1) + 1;
+	const openingPrefix = markdown.slice(lineStart, start);
+	const prefix = hasClosing
+		? closeMatch[1]
+		: openingPrefix.replace(/(?:[-+*]|\d+[.)])([ \t]+)/g, (marker) => " ".repeat(marker.length));
+	const closing = hasClosing ? lastLine : prefix + fence;
+	const openingLine = opening[0].endsWith("\n") ? opening[0] : opening[0] + "\n";
+	const trailingNewline = !hasClosing && original.endsWith("\n") ? "\n" : "";
+	return {
+		source: node.value,
+		replace(source: string) {
+			const body = source
+				.replace(/\r\n/g, "\n")
+				.trimEnd()
+				.split("\n")
+				.map((line) => prefix + line)
+				.join("\n");
+			return (
+				markdown.slice(0, start) +
+				openingLine +
+				body +
+				"\n" +
+				closing +
+				trailingNewline +
+				markdown.slice(end)
+			);
+		},
+	};
+}