@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/file-system-access.d.ts

@@ -0,0 +1,29 @@
+// TS 7.0.2's DOM lib doesn't (yet) declare the File System Access API this
+// module uses (client/export-save.ts). Only what's actually used is declared
+// here — trim or extend this file if `yarn typecheck` disagrees.
+
+interface SaveFilePickerOptions {
+	suggestedName?: string;
+	types?: { description?: string; accept: Record<string, string[]> }[];
+}
+
+interface FileSystemWritableFileStream {
+	write(data: Blob | BufferSource | string): Promise<void>;
+	close(): Promise<void>;
+}
+
+interface FileSystemFileHandle {
+	createWritable(): Promise<FileSystemWritableFileStream>;
+}
+
+interface Window {
+	showSaveFilePicker?: (options?: SaveFilePickerOptions) => Promise<FileSystemFileHandle>;
+}
+
+interface UserActivation {
+	readonly isActive: boolean;
+}
+
+interface Navigator {
+	readonly userActivation?: UserActivation;
+}

package/client/format.ts

@@ -0,0 +1,17 @@
+import { formatDistanceToNow } from "date-fns";
+
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function formatModified(mtime: number): string {
+	return formatDistanceToNow(mtime, { addSuffix: true });
+}
+
+/** "/Users/karim/foo" -> "~/foo" (best-effort; the client has no direct os.homedir()). */
+export function shortenHome(dir: string): string {
+	const match = dir.match(/^\/(?:Users|home)\/[^/]+/);
+	return match ? `~${dir.slice(match[0].length)}` : dir;
+}

package/client/hooks.ts

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+
+/** Returns `value`, updated only after it has stayed unchanged for `delayMs`. */
+export function useDebounced<Value>(value: Value, delayMs: number): Value {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+
+	useEffect(() => {
+		const handle = setTimeout(() => setDebouncedValue(value), delayMs);
+		return () => clearTimeout(handle);
+	}, [value, delayMs]);
+
+	return debouncedValue;
+}
+
+/**
+ * Whether the viewport matches a CSS media query, kept live as the window is
+ * resized. The SSR pass has no viewport, so it reports `serverDefault`; the
+ * store swaps in the real answer on hydration without a mismatch.
+ */
+export function useMediaQuery(query: string, serverDefault = false): boolean {
+	const subscribe = useCallback(
+		(onChange: () => void) => {
+			const list = window.matchMedia(query);
+			list.addEventListener("change", onChange);
+			return () => list.removeEventListener("change", onChange);
+		},
+		[query],
+	);
+	return useSyncExternalStore(
+		subscribe,
+		() => window.matchMedia(query).matches,
+		() => serverDefault,
+	);
+}

package/client/lucide-icons.d.ts

@@ -0,0 +1,9 @@
+// lucide-react ships one .mjs file per icon under dist/esm/icons/ (no .d.ts
+// alongside them) so a deep import like
+// `import ArrowLeft from "lucide-react/dist/esm/icons/arrow-left.mjs"` has no
+// type on its own. This ambient module covers every such deep import with the
+// same shape lucide-react's own named exports use.
+declare module "lucide-react/dist/esm/icons/*" {
+	const icon: import("lucide-react").LucideIcon;
+	export default icon;
+}

package/client/mdx-components-base.ts

@@ -0,0 +1,32 @@
+import type { ComponentType } from "react";
+// This module (and everything it pulls in — every builtin, transitively) is
+// reachable from the SSR entry (client/ssr-entry.tsx) that validate_doc's
+// render check loads via Vite's SSR module runner, and from
+// client/standalone-entry.tsx's build output. Nothing in this file or its
+// dependency graph may import client/router.ts (it touches `window` and the
+// query cache at module scope). client/api.ts is the one exception:
+// MdSection imports its `trpcClient`, and api.ts is written to evaluate
+// without a `window` for exactly that reason — keep it that way, and keep
+// every package it imports in src/rendering/vite.ts's `ssr.optimizeDeps.include`.
+import { TaskCheckbox } from "./TaskCheckbox";
+import { Figure, Pre } from "./CodeBlock";
+import { H2, H3, H4 } from "./Heading";
+import { Table } from "./Table";
+import { builtinComponents } from "./builtins/index";
+
+/**
+ * The `MDXProvider` component map shared by every render path that does not
+ * need `MdSection` — the browser entry, the SSR entry, and the standalone
+ * build entry. client/mdx-components.ts adds `MdSection` on top for the live
+ * server's browser entry.
+ */
+export const mdxComponentsBase: Record<string, ComponentType<any>> = {
+	...builtinComponents,
+	pre: Pre,
+	figure: Figure,
+	h2: H2,
+	h3: H3,
+	h4: H4,
+	input: TaskCheckbox,
+	table: Table,
+};

package/client/mdx-components.ts

@@ -0,0 +1,18 @@
+import type { ComponentType } from "react";
+import { MdSection } from "./MdSection";
+import { mdxComponentsBase } from "./mdx-components-base";
+
+/**
+ * The `MDXProvider` component map shared by both the browser entry
+ * (`client/entry.tsx`) and the SSR entry (`client/ssr-entry.tsx`), so the two
+ * render paths cannot drift apart.
+ */
+export const mdxComponents: Record<string, ComponentType<any>> = {
+	...mdxComponentsBase,
+	// The remark-sections compiler plugin (src/rendering/mdx/remark-sections.ts, server-owned)
+	// wraps every editable run of top-level markdown nodes in this synthetic
+	// element. It is NOT in the base compile options seen by validate_doc's
+	// static registry check (src/rendering/mdx/mdx-options.ts), only in the live Vite config
+	// — so it must be registered here (SSR-safe) but never listed as a builtin.
+	MdSection,
+};

package/client/mermaid-chart.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared, framework-free mermaid header detection: locating the line that
+ * names a mermaid diagram's type (skipping blank lines, a leading `---`
+ * front-matter block, `%%` comments, and multi-line `%%{init: …}%%`
+ * directives), and recognising the handful of diagram types that draw
+ * charts of data — the kind mdxserve's builtin `<Chart>` component already
+ * covers, and renders far better (design tokens, hover, expand).
+ *
+ * Pure and import-free like `client/mermaid-direction.ts`, so it is safe to
+ * ship in the browser bundle. `src/` importing a pure module from `client/`
+ * is fine — the AGENTS.md rule against crossing the boundary is
+ * one-directional, and `scripts/build-registry.ts` already imports
+ * `client/builtins/index.ts` the same way — but this file itself must stay
+ * import-free and browser-safe: no `src/`, no Node builtins, no React.
+ */
+
+export const CHART_DIAGRAM_KEYWORDS = [
+	"pie",
+	"xychart-beta",
+	"quadrantChart",
+	"sankey-beta",
+] as const;
+
+export type ChartDiagramKeyword = (typeof CHART_DIAGRAM_KEYWORDS)[number];
+
+const CHART_HEADER_PATTERNS: Record<ChartDiagramKeyword, RegExp> = {
+	pie: /^pie(?:\s|$)/,
+	"xychart-beta": /^xychart-beta(?:\s|$)/,
+	quadrantChart: /^quadrantChart(?:\s|$)/,
+	"sankey-beta": /^sankey-beta(?:\s|$)/,
+};
+
+const CHART_DIAGRAM_ALTERNATIVES: Record<ChartDiagramKeyword, string> = {
+	pie: "use a bar chart or a table for part-to-whole",
+	"xychart-beta": 'use type="bar" or type="line"',
+	quadrantChart: "use a table (one row per item, a column per axis)",
+	"sankey-beta": "use a table, or totals as bars",
+};
+
+/**
+ * Index of the line in `lines` that starts the diagram's content: blanks, a
+ * leading `---` front-matter block, `%%` comment lines, and a directive that
+ * spans several lines (`%%{init: {\n …\n }}%%`) are all skipped. -1 when the
+ * source has no such line (empty, or an unclosed front-matter block).
+ */
+export function mermaidHeaderLineIndex(lines: string[]): number {
+	let index = 0;
+	while (index < lines.length && lines[index]!.trim() === "") index++;
+	if (lines[index]?.trim() === "---") {
+		const close = lines.findIndex((line, at) => at > index && line.trim() === "---");
+		if (close === -1) return -1;
+		index = close + 1;
+	}
+	let inDirective = false;
+	for (; index < lines.length; index++) {
+		const line = lines[index]!;
+		if (inDirective) {
+			if (line.includes("}%%")) inDirective = false;
+			continue;
+		}
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		if (trimmed.startsWith("%%")) {
+			if (trimmed.startsWith("%%{") && !trimmed.includes("}%%")) inDirective = true;
+			continue;
+		}
+		return index;
+	}
+	return -1;
+}
+
+/**
+ * The trimmed header line of a mermaid fence's `source`, or `undefined` when
+ * there isn't one (an empty fence, or an unclosed front-matter block).
+ */
+export function mermaidHeaderLine(source: string): string | undefined {
+	const lines = source.split(/\r?\n/);
+	const index = mermaidHeaderLineIndex(lines);
+	return index === -1 ? undefined : lines[index]!.trim();
+}
+
+/**
+ * The chart-diagram keyword a mermaid `source` opens with, or `null` for
+ * every other diagram type (flow, sequence, class, state, ER, gantt,
+ * timeline, gitGraph, mindmap, journey, C4, …). Matches on a word boundary,
+ * so `pieChart`, `xychart`, and `sankey` (near-misses, not the real
+ * keywords) never match, and the keyword must be the header line itself —
+ * one appearing later in the body does not count.
+ */
+export function chartDiagramKeyword(source: string): ChartDiagramKeyword | null {
+	const header = mermaidHeaderLine(source);
+	if (header === undefined) return null;
+	for (const keyword of CHART_DIAGRAM_KEYWORDS) {
+		if (CHART_HEADER_PATTERNS[keyword].test(header)) return keyword;
+	}
+	return null;
+}
+
+/**
+ * The one steer shown to a reader (in the "don't render here" card) and an
+ * agent (in a `validate_doc` diagnostic) for a rejected chart diagram.
+ */
+export function chartDiagramMessage(keyword: ChartDiagramKeyword): string {
+	return (
+		`Mermaid \`${keyword}\` charts do not render in mdxserve. Use the builtin <Chart> ` +
+		`component instead (type="bar" | "line" | "area" | "histogram", orientation="horizontal" ` +
+		`for horizontal bars) — ${CHART_DIAGRAM_ALTERNATIVES[keyword]}.`
+	);
+}

package/client/mermaid-direction.ts

@@ -0,0 +1,73 @@
+/**
+ * Read and rewrite the layout direction of a mermaid flowchart without touching
+ * anything else in the source. The reader can flip a diagram between top-down
+ * and left-right for their own view; the markdown on disk (and the text the
+ * copy button hands out) is never changed, so these helpers are the only place
+ * that knows how a direction is spelled.
+ *
+ * Mermaid spells the header as `flowchart LR`, `graph TD`, `flowchart-elk BT`,
+ * optionally with a trailing `;`, and treats `TD` as an alias of `TB`. It may be
+ * preceded by a `---` front-matter block, `%%` comments, and `%%{init: …}%%`
+ * directives, which is why the header is located line by line instead of with
+ * a single anchored regex — `mermaidHeaderLineIndex` (`./mermaid-chart.js`)
+ * does that scan; this file only checks whether the line it finds is a
+ * flowchart header.
+ */
+
+import { mermaidHeaderLineIndex } from "./mermaid-chart.js";
+
+export const FLOW_DIRECTIONS = ["TB", "BT", "LR", "RL"] as const;
+
+export type FlowDirection = (typeof FLOW_DIRECTIONS)[number];
+
+/**
+ * Captures the keyword (1), the whitespace before the direction (2) and the
+ * direction (3); the lookahead keeps `graphs` or `flowchartX` from matching.
+ */
+const HEADER = /^(\s*(?:flowchart|graph)(?:-elk)?)(?:(\s+)(TB|TD|BT|LR|RL))?(?=[\s;]|$)/;
+
+function normalize(direction: string): FlowDirection {
+	return direction === "TD" ? "TB" : (direction as FlowDirection);
+}
+
+/**
+ * Index of the line holding the `flowchart`/`graph` header, or -1 when the
+ * source is not a flowchart. `mermaidHeaderLineIndex` does the scan past a
+ * leading front-matter block and any comment or directive lines; this only
+ * adds the flowchart-specific check on the line it finds.
+ */
+function headerLineIndex(lines: string[]): number {
+	const index = mermaidHeaderLineIndex(lines);
+	return index !== -1 && HEADER.test(lines[index]!) ? index : -1;
+}
+
+/**
+ * The direction a flowchart lays out in, or null when `source` is some other
+ * kind of diagram. A bare `flowchart` header with no direction reads as `TB`,
+ * which is what mermaid falls back to.
+ */
+export function readFlowchartDirection(source: string): FlowDirection | null {
+	const lines = source.split("\n");
+	const index = headerLineIndex(lines);
+	if (index === -1) return null;
+	const match = HEADER.exec(lines[index]!);
+	return normalize(match?.[3] ?? "TB");
+}
+
+/**
+ * `source` with its flowchart laid out in `direction`. Only the header line
+ * changes; a source that is not a flowchart, or one already in that direction
+ * (`TD` counts as `TB`), comes back unchanged.
+ */
+export function setFlowchartDirection(source: string, direction: FlowDirection): string {
+	const lines = source.split("\n");
+	const index = headerLineIndex(lines);
+	if (index === -1) return source;
+	const header = lines[index]!;
+	const match = HEADER.exec(header);
+	if (!match) return source;
+	if (normalize(match[3] ?? "TB") === direction) return source;
+	const rest = header.slice(match[0].length);
+	lines[index] = `${match[1]}${match[2] ?? " "}${direction}${rest}`;
+	return lines.join("\n");
+}

package/client/motion.ts

@@ -0,0 +1,104 @@
+import type { Transition, Variants } from "framer-motion";
+
+/** Shared ease for every subtle motion in the app: a gentle deceleration. */
+export const subtleEase = [0.22, 1, 0.36, 1] as const;
+
+export const enterTransition: Transition = { duration: 0.2, ease: subtleEase };
+export const exitTransition: Transition = { duration: 0.15, ease: subtleEase };
+export const fadeSwapTransition: Transition = { duration: 0.12, ease: subtleEase };
+
+/**
+ * Fade + slight vertical rise. Used for page-level view transitions (App.tsx)
+ * and card-level entrances (CodeFrame, Callout).
+ */
+export const fadeRise: Variants = {
+	initial: { opacity: 0, y: 8 },
+	enter: { opacity: 1, y: 0, transition: enterTransition },
+	exit: { opacity: 0, y: -6, transition: exitTransition },
+};
+
+/** Opacity-only cross-fade for swapping small bits of content in place (labels, toggled views). */
+export const fadeSwap: Variants = {
+	initial: { opacity: 0 },
+	enter: { opacity: 1, transition: fadeSwapTransition },
+	exit: { opacity: 0, transition: fadeSwapTransition },
+};
+
+/** Stagger container for groups of items that should enter together (listing rows). */
+export const stagger: Variants = {
+	initial: {},
+	enter: { transition: { staggerChildren: 0.02 } },
+};
+
+/* ── Design-system motion (mirrors client/design-ref/components/motion/MotionKit.jsx
+   and the --spring-* / --dur-* tokens in client/design/tokens/motion.css).
+   Springs for anything physical, tweens for colour and opacity only. Nothing
+   overshoots past 2%, nothing travels more than 10px. ── */
+
+export const TRANSITIONS = {
+	/** Controls: press, toggle knobs, segmented pills. 1:1 with --spring-snap. */
+	snap: { type: "spring", stiffness: 620, damping: 34, mass: 0.7 } satisfies Transition,
+	/** Surfaces: dialogs, toasts, disclosure. 1:1 with --spring-glide. */
+	glide: { type: "spring", stiffness: 340, damping: 30, mass: 0.9 } satisfies Transition,
+	/** Colour and opacity only. */
+	fast: { duration: 0.12, ease: [0.2, 0, 0.2, 1] } satisfies Transition,
+	base: { duration: 0.18, ease: [0.2, 0, 0.2, 1] } satisfies Transition,
+	slow: { duration: 0.26, ease: [0, 0, 0.2, 1] } satisfies Transition,
+};
+
+type Entrance = {
+	initial: Record<string, number | string>;
+	animate: Record<string, number | string>;
+	exit?: Record<string, number | string | Transition>;
+	transition: Transition;
+};
+
+/** Named entrances, so every surface of the same class enters identically. Spread onto a `motion.*`. */
+export const VARIANTS = {
+	/** Tooltips, inline swaps: opacity only. */
+	fade: {
+		initial: { opacity: 0 },
+		animate: { opacity: 1 },
+		exit: { opacity: 0 },
+		transition: TRANSITIONS.base,
+	},
+	/** Dialogs and the search palette. */
+	pop: {
+		initial: { opacity: 0, y: 6, scale: 0.985 },
+		animate: { opacity: 1, y: 0, scale: 1 },
+		exit: { opacity: 0, y: 4, scale: 0.99, transition: TRANSITIONS.fast },
+		transition: TRANSITIONS.glide,
+	},
+	/** Toasts, from the bottom-right stack. */
+	slideUp: {
+		initial: { opacity: 0, y: 10, scale: 0.98 },
+		animate: { opacity: 1, y: 0, scale: 1 },
+		exit: { opacity: 0, x: 16, transition: TRANSITIONS.fast },
+		transition: TRANSITIONS.glide,
+	},
+	/** Scrims behind a modal surface. */
+	scrim: {
+		initial: { opacity: 0 },
+		animate: { opacity: 1 },
+		exit: { opacity: 0 },
+		transition: TRANSITIONS.fast,
+	},
+	/** Collapsible nav groups and diagram/code swaps. */
+	collapse: {
+		initial: { opacity: 0, height: 0 },
+		animate: { opacity: 1, height: "auto" },
+		exit: { opacity: 0, height: 0 },
+		transition: TRANSITIONS.glide,
+	},
+	/** Page and section content, 6px up. */
+	rise: {
+		initial: { opacity: 0, y: 6 },
+		animate: { opacity: 1, y: 0 },
+		transition: TRANSITIONS.glide,
+	},
+} satisfies Record<string, Entrance>;
+
+/** Stagger a list of children by 40ms each (search results cap at 5). */
+export function staggerBy(delay = 0.04): Variants {
+	return { animate: { transition: { staggerChildren: delay } } };
+}

package/client/platform.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether the user is on an Apple platform, for keyboard hints (⌘ vs Ctrl).
+ * Shared by TopBar's search hint and the section editor's save/cancel hints.
+ * `navigator.platform` is deprecated but still the one signal every browser
+ * exposes synchronously; guard it so the SSR render worker can import this.
+ */
+export function isApplePlatform(): boolean {
+	return typeof navigator !== "undefined" && /Mac|iPhone|iPod|iPad/.test(navigator.platform);
+}
+
+/**
+ * The viewport width at which the shell docks the sidebar instead of using a
+ * drawer — Tailwind's `md`. Anything narrower is treated as a phone-sized
+ * screen by every component that adapts its layout.
+ */
+export const DESKTOP_MEDIA = "(min-width: 768px)";

package/client/route-path.ts

@@ -0,0 +1,15 @@
+/**
+ * A pathname straight from `URL.pathname` / `location.pathname` is
+ * percent-encoded (`/docs/My%20Page.md`), while the server embeds the decoded
+ * form in the initial route and every API takes decoded filesystem paths.
+ * Routes created on the client go through this so `route.path` is always the
+ * decoded form. A stray `%` that is not a valid escape is kept as-is rather
+ * than thrown on.
+ */
+export function decodeRoutePath(pathname: string): string {
+	try {
+		return decodeURIComponent(pathname);
+	} catch {
+		return pathname;
+	}
+}