@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/design/tokens/colors.css

@@ -0,0 +1,188 @@
+/* ── mdxserve colors ───────────────────────────────────────────────
+   Warm neutral paper + one deep teal accent. Content is the subject;
+   chrome is neutral, accent is used sparingly for state and links. */
+:root {
+	/* neutrals — warm grey "paper" ramp */
+	--n-0: #ffffff;
+	--n-25: #fbfbf9;
+	--n-50: #f6f6f3;
+	--n-100: #eeeeea;
+	--n-200: #e3e2dd;
+	--n-300: #cfcec7;
+	--n-400: #a9a8a0;
+	--n-500: #82817a;
+	--n-600: #615f5a;
+	--n-700: #464540;
+	--n-800: #2b2a27;
+	--n-900: #1a1918;
+	--n-950: #111110;
+
+	/* accent — deep teal */
+	--teal-50: #e8f6f5;
+	--teal-100: #c9eae8;
+	--teal-200: #9bd8d5;
+	--teal-300: #63c1be;
+	--teal-400: #2ba5a2;
+	--teal-500: #0e8f8c;
+	/* fill under white text (primary button, checkbox): the one step that
+	   clears 4.5:1 on white and 3:1 against both page grounds */
+	--teal-550: #0c8280;
+	--teal-600: #0a7472;
+	--teal-700: #085b59;
+	--teal-800: #064442;
+	--teal-900: #042c2b;
+
+	/* support hues — semantic + diagram fills only, never decoration */
+	--blue-100: #dce7fd;
+	--blue-500: #2f6fed;
+	--blue-700: #1d4dab;
+	--green-100: #d8f0e3;
+	--green-500: #1a7f4f;
+	--green-700: #12603b;
+	--amber-100: #fbeccd;
+	--amber-500: #b07405;
+	--amber-700: #855603;
+	--red-100: #fbdfd9;
+	--red-500: #c8412f;
+	--red-700: #9a2f20;
+	--violet-100: #e6e2fb;
+	--violet-500: #5b4fd0;
+	--violet-700: #433a9e;
+
+	/* ── semantic aliases ── */
+	--surface-page: var(--n-25);
+	--surface-card: var(--n-0);
+	--surface-sunken: var(--n-50);
+	--surface-raised: var(--n-0);
+	--surface-inverse: var(--n-900);
+	--surface-hover: var(--n-100);
+	--surface-active: var(--n-200);
+	--surface-accent-soft: var(--teal-50);
+	--surface-accent: var(--teal-550);
+
+	--text-body: var(--n-800);
+	--text-heading: var(--n-950);
+	--text-muted: var(--n-600);
+	--text-subtle: var(--n-500);
+	--text-inverse: var(--n-25);
+	--text-accent: var(--teal-600);
+	--text-link: var(--teal-600);
+	--text-link-hover: var(--teal-700);
+
+	--border-subtle: var(--n-100);
+	--border-default: var(--n-200);
+	--border-strong: var(--n-300);
+	--border-accent: var(--teal-400);
+	--focus-ring: color-mix(in oklab, var(--teal-500) 45%, transparent);
+
+	--status-info-bg: var(--blue-100);
+	--status-info-fg: var(--blue-700);
+	--status-ok-bg: var(--green-100);
+	--status-ok-fg: var(--green-700);
+	--status-warn-bg: var(--amber-100);
+	--status-warn-fg: var(--amber-700);
+	--status-danger-bg: var(--red-100);
+	--status-danger-fg: var(--red-700);
+	--status-note-bg: var(--violet-100);
+	--status-note-fg: var(--violet-700);
+
+	/* diagrams + charts — categorical series, in order of use */
+	--chart-1: var(--teal-500);
+	--chart-2: var(--blue-500);
+	--chart-3: var(--amber-500);
+	--chart-4: var(--violet-500);
+	--chart-5: var(--green-500);
+	--chart-6: var(--red-500);
+	--chart-grid: var(--border-subtle);
+	--chart-axis: var(--n-300);
+	--chart-label: var(--text-subtle);
+	--diagram-bg: var(--surface-card);
+	--diagram-node-bg: var(--surface-accent-soft);
+	--diagram-node-border: var(--teal-400);
+	--diagram-node-fg: var(--teal-700);
+	--diagram-alt-node-bg: var(--surface-sunken);
+	--diagram-alt-node-border: var(--border-strong);
+	--diagram-line: var(--n-400);
+	--diagram-label-bg: var(--surface-card);
+
+	/* code surfaces + syntax */
+	--code-bg: var(--n-50);
+	--code-bg-inline: var(--teal-50);
+	--code-fg: var(--n-800);
+	--code-border: var(--n-200);
+	--code-gutter: var(--n-400);
+	--code-highlight: color-mix(in oklab, var(--teal-500) 9%, transparent);
+	--syntax-keyword: #8a3fa8;
+	--syntax-string: #0a7472;
+	--syntax-number: #b07405;
+	--syntax-comment: #82817a;
+	--syntax-function: #2f6fed;
+	--syntax-tag: #c8412f;
+	--syntax-attr: #5b4fd0;
+	--syntax-punct: #615f5a;
+}
+
+/* Dark: the pre-design-system blue-black (Tailwind gray-950) kept on request — a
+   cool near-black ramp instead of the warm one the design project shipped
+   (#141514). Teal is lifted for contrast exactly as in the design. */
+:root[data-theme="dark"] {
+	--surface-page: #030712;
+	--surface-card: #0b1120;
+	--surface-sunken: #020509;
+	--surface-raised: #111827;
+	--surface-inverse: var(--n-50);
+	--surface-hover: #1b2436;
+	--surface-active: #263044;
+	--surface-accent-soft: var(--teal-900);
+	--surface-accent: var(--teal-550);
+
+	--text-body: #d1d5db;
+	--text-heading: #f9fafb;
+	--text-muted: #9ca3af;
+	--text-subtle: #6b7280;
+	--text-inverse: var(--n-950);
+	--text-accent: var(--teal-300);
+	--text-link: var(--teal-300);
+	--text-link-hover: var(--teal-200);
+
+	--border-subtle: #111827;
+	--border-default: #1f2937;
+	--border-strong: #374151;
+	--border-accent: var(--teal-400);
+
+	--status-info-bg: #182a4d;
+	--status-info-fg: #9dbcfb;
+	--status-ok-bg: #122f22;
+	--status-ok-fg: #8fd8b0;
+	--status-warn-bg: #33260a;
+	--status-warn-fg: #e9c078;
+	--status-danger-bg: #39190f;
+	--status-danger-fg: #eda99b;
+	--status-note-bg: #221d44;
+	--status-note-fg: #b9b1f2;
+
+	--chart-1: var(--teal-300);
+	--chart-2: #8db3fb;
+	--chart-3: #e9c078;
+	--chart-4: #b9b1f2;
+	--chart-5: #8fd8b0;
+	--chart-6: #eda99b;
+	--chart-grid: #111827;
+	--chart-axis: #1f2937;
+	--diagram-node-fg: var(--teal-200);
+	--diagram-line: #4b5563;
+
+	--code-bg: #0b1120;
+	--code-bg-inline: #0f2422;
+	--code-fg: #d1d5db;
+	--code-border: #1f2937;
+	--code-gutter: #4b5563;
+	--syntax-keyword: #d79ae8;
+	--syntax-string: #63c1be;
+	--syntax-number: #e9c078;
+	--syntax-comment: #6b7280;
+	--syntax-function: #8db3fb;
+	--syntax-tag: #eda99b;
+	--syntax-attr: #b9b1f2;
+	--syntax-punct: #9ca3af;
+}

package/client/design/tokens/elevation.css

@@ -0,0 +1,42 @@
+:root {
+	/* radii — 6px is the default; nothing in the system is pill-shaped except tags/kbd */
+	--radius-xs: 3px;
+	--radius-sm: 4px;
+	--radius-md: 6px;
+	--radius-lg: 10px;
+	--radius-xl: 14px;
+	--radius-pill: 999px;
+
+	--border-width: 1px;
+	--border-width-thick: 2px;
+
+	/* shadows — hairline-first. Borders do the work; shadow only signals lift. */
+	--shadow-none: none;
+	--shadow-hairline: 0 0 0 1px var(--border-default);
+	--shadow-xs: 0 1px 2px rgba(26, 25, 24, 0.05);
+	--shadow-sm: 0 1px 2px rgba(26, 25, 24, 0.05), 0 2px 6px rgba(26, 25, 24, 0.04);
+	--shadow-md: 0 2px 4px rgba(26, 25, 24, 0.05), 0 8px 20px rgba(26, 25, 24, 0.07);
+	--shadow-lg: 0 4px 8px rgba(26, 25, 24, 0.06), 0 18px 44px rgba(26, 25, 24, 0.11);
+	--shadow-inset: inset 0 1px 0 rgba(255, 255, 255, 0.6);
+	--shadow-focus: 0 0 0 3px var(--focus-ring);
+	/* The one deliberate coloured ring/glow in the system — toasts only. */
+	--shadow-toast:
+		0 0 0 1px rgba(43, 165, 162, 0.18), 0 8px 24px rgba(43, 165, 162, 0.12),
+		0 2px 4px rgba(26, 25, 24, 0.05), 0 8px 20px rgba(26, 25, 24, 0.07);
+
+	/* glass — used only for the sticky topbar and the command palette scrim */
+	--blur-chrome: saturate(1.4) blur(12px); /* @kind other */
+	--scrim: color-mix(in oklab, var(--n-950) 34%, transparent); /* @kind color */
+}
+
+:root[data-theme="dark"] {
+	--shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.4);
+	--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4), 0 2px 6px rgba(0, 0, 0, 0.3);
+	--shadow-md: 0 2px 4px rgba(0, 0, 0, 0.4), 0 8px 20px rgba(0, 0, 0, 0.45);
+	--shadow-lg: 0 4px 8px rgba(0, 0, 0, 0.45), 0 18px 44px rgba(0, 0, 0, 0.55);
+	--shadow-inset: inset 0 1px 0 rgba(255, 255, 255, 0.05);
+	--shadow-toast:
+		0 0 0 1px rgba(43, 165, 162, 0.28), 0 8px 24px rgba(43, 165, 162, 0.22),
+		0 2px 4px rgba(0, 0, 0, 0.4), 0 8px 20px rgba(0, 0, 0, 0.45);
+	--scrim: rgba(0, 0, 0, 0.6);
+}

package/client/design/tokens/fonts.css

@@ -0,0 +1,6 @@
+/* Webfonts, self-hosted from the @fontsource-variable packages so mdxserve works
+   offline and never phones out to a font CDN. Explicit index.css subpaths: the
+   Tailwind CSS resolver that processes these imports does not try package
+   "index" files on its own. */
+@import "@fontsource-variable/manrope/index.css";
+@import "@fontsource-variable/jetbrains-mono/index.css";

package/client/design/tokens/motion.css

@@ -0,0 +1,76 @@
+:root {
+	/* Motion is short and flat. Nothing bounces past 2%; nothing travels over 10px.
+     Springs are the default for anything a person touches or that changes size;
+     tweens are for colour and opacity only. Implemented with Framer Motion via
+     components/motion/MotionKit.jsx — these tokens are the same numbers. */
+	--dur-instant: 80ms; /* @kind other */
+	--dur-fast: 120ms; /* @kind other */
+	--dur-base: 180ms; /* @kind other */
+	--dur-slow: 260ms; /* @kind other */
+	--ease-standard: cubic-bezier(0.2, 0, 0.2, 1); /* @kind other */
+	--ease-out: cubic-bezier(0, 0, 0.2, 1); /* @kind other */
+	--ease-in: cubic-bezier(0.4, 0, 1, 1); /* @kind other */
+
+	--transition-color:
+		color var(--dur-fast) var(--ease-standard),
+		background-color var(--dur-fast) var(--ease-standard),
+		border-color var(--dur-fast) var(--ease-standard);
+	--transition-lift:
+		box-shadow var(--dur-base) var(--ease-standard), transform var(--dur-fast) var(--ease-standard);
+
+	/* Springs — mirrored in MotionKit's T.snap / T.glide. */
+	--spring-snap: 620 34 0.7; /* @kind other */
+	--spring-glide: 340 30 0.9; /* @kind other */
+
+	/* Travel distances. Anything larger reads as a page transition, which this system has none of. */
+	--travel-xs: 4px;
+	--travel-sm: 6px;
+	--travel-md: 10px;
+	--press-offset: 0.5px;
+	--hover-nudge: 2px;
+	--pop-scale: 0.985; /* @kind other */
+	--enter-pop: popIn var(--dur-base) var(--ease-out);
+	--enter-fade: fadeIn var(--dur-base) var(--ease-out);
+
+	--z-sticky: 10; /* @kind other */
+	--z-dropdown: 40; /* @kind other */
+	--z-scrim: 60; /* @kind other */
+	--z-modal: 70; /* @kind other */
+	--z-toast: 80; /* @kind other */
+}
+@keyframes fadeIn {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}
+@keyframes popIn {
+	from {
+		opacity: 0;
+		transform: translateY(4px) scale(0.985);
+	}
+	to {
+		opacity: 1;
+		transform: none;
+	}
+}
+@keyframes slideUp {
+	from {
+		opacity: 0;
+		transform: translateY(8px);
+	}
+	to {
+		opacity: 1;
+		transform: none;
+	}
+}
+@media (prefers-reduced-motion: reduce) {
+	:root {
+		--dur-instant: 0ms; /* @kind other */
+		--dur-fast: 0ms; /* @kind other */
+		--dur-base: 0ms; /* @kind other */
+		--dur-slow: 0ms /* @kind other */;
+	}
+}

package/client/design/tokens/spacing.css

@@ -0,0 +1,34 @@
+:root {
+	/* 4px base, with 2px and 6px steps where UI density needs them */
+	--space-0: 0;
+	--space-px: 1px;
+	--space-0-5: 2px;
+	--space-1: 4px;
+	--space-1-5: 6px;
+	--space-2: 8px;
+	--space-2-5: 10px;
+	--space-3: 12px;
+	--space-4: 16px;
+	--space-5: 20px;
+	--space-6: 24px;
+	--space-7: 28px;
+	--space-8: 32px;
+	--space-10: 40px;
+	--space-12: 48px;
+	--space-16: 64px;
+	--space-20: 80px;
+	--space-24: 96px;
+	--space-32: 128px;
+
+	/* rhythm — vertical spacing inside rendered markdown */
+	--prose-gap: var(--space-5);
+	--prose-gap-heading: var(--space-8);
+	--prose-gap-block: var(--space-6);
+
+	/* layout */
+	--sidebar-width: 264px;
+	--toc-width: 220px;
+	--topbar-height: 52px;
+	--gutter-page: var(--space-8);
+	--gutter-page-lg: var(--space-12);
+}

package/client/design/tokens/typography.css

@@ -0,0 +1,56 @@
+:root {
+	--font-core:
+		"Manrope Variable", "Manrope", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+	--font-mono:
+		"JetBrains Mono Variable", "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+
+	--weight-regular: 400;
+	--weight-medium: 500;
+	--weight-semibold: 600;
+	--weight-bold: 700;
+	--weight-extrabold: 800;
+
+	/* size ramp — 15px UI base, 16.5px prose base */
+	--size-2xs: 11px;
+	--size-xs: 12px;
+	--size-sm: 13px;
+	--size-md: 15px;
+	--size-prose: 16.5px;
+	--size-lg: 18px;
+	--size-xl: 21px;
+	--size-2xl: 26px;
+	--size-3xl: 32px;
+	--size-4xl: 40px;
+	--size-5xl: 52px;
+	--size-6xl: 68px;
+
+	--leading-tight: 1.15;
+	--leading-snug: 1.3;
+	--leading-normal: 1.5;
+	--leading-prose: 1.72;
+	--leading-code: 1.62;
+
+	--tracking-tight: -0.022em;
+	--tracking-snug: -0.012em;
+	--tracking-normal: 0;
+	--tracking-wide: 0.04em;
+	--tracking-caps: 0.09em;
+
+	/* composed roles */
+	--type-display: var(--weight-extrabold) var(--size-5xl)/var(--leading-tight) var(--font-core);
+	--type-h1: var(--weight-bold) var(--size-3xl)/1.2 var(--font-core);
+	--type-h2: var(--weight-bold) var(--size-2xl)/1.25 var(--font-core);
+	--type-h3: var(--weight-semibold) var(--size-xl)/1.35 var(--font-core);
+	--type-h4: var(--weight-semibold) var(--size-lg)/1.4 var(--font-core);
+	--type-prose: var(--weight-regular) var(--size-prose)/var(--leading-prose) var(--font-core);
+	--type-ui: var(--weight-medium) var(--size-md)/var(--leading-normal) var(--font-core);
+	--type-ui-sm: var(--weight-medium) var(--size-sm)/var(--leading-normal) var(--font-core);
+	--type-code: var(--weight-regular) var(--size-sm)/var(--leading-code) var(--font-mono);
+	--type-code-inline: var(--weight-medium) 0.88em/1.4 var(--font-mono);
+	--type-eyebrow: var(--weight-semibold) var(--size-2xs)/1.2 var(--font-mono);
+
+	/* prose measure */
+	--measure-prose: none; /* @kind other */
+	--width-prose: 44rem;
+	--width-content: 52rem;
+}

package/client/doc-module-cache.ts

@@ -0,0 +1,17 @@
+import type { ComponentType } from "react";
+
+export type DocModuleState =
+	{ status: "ok"; Component: ComponentType } | { status: "error"; message: string };
+
+/**
+ * Modules imported for doc routes, keyed by the doc's path (its absolute path
+ * in the live viewer, an opaque key in an exported file). Shared across the
+ * whole session (module scope, not component state) so DocView can render
+ * synchronously once a route resolves, and so re-visiting a doc doesn't
+ * re-trigger the dynamic import.
+ *
+ * Lives in its own module — not client/router.ts — so the standalone shell
+ * (client/standalone-entry.tsx) can seed and read it without pulling the
+ * router's tRPC/react-query graph into an exported file.
+ */
+export const docModuleCache = new Map<string, DocModuleState>();

package/client/editor-link.ts

@@ -0,0 +1,27 @@
+/**
+ * The subset of a `MouseEvent` that decides whether a click on a link inside
+ * the section editor should open it. Pure so it can be tested without a DOM.
+ */
+export interface LinkClick {
+	button: number;
+	metaKey: boolean;
+	ctrlKey: boolean;
+}
+
+/**
+ * The href a click inside the editor should open in a new tab, or `null` to
+ * let ProseMirror place the caret as usual.
+ *
+ * In read mode a link is a link, so cmd/ctrl+click gets the browser's own
+ * new-tab behaviour. Inside the contenteditable that default never fires —
+ * the browser treats the anchor as editable text — and Tiptap's Link
+ * extension is configured with `openOnClick: false` so a plain click can edit
+ * the link's text. That leaves the editor convention every other editor
+ * (VS Code, Notion, Google Docs) follows: hold cmd (or ctrl) to follow it.
+ */
+export function modifiedLinkHref(click: LinkClick, href: string | null | undefined): string | null {
+	if (click.button !== 0) return null;
+	if (!(click.metaKey || click.ctrlKey)) return null;
+	if (!href) return null;
+	return href;
+}

package/client/entry.tsx

@@ -0,0 +1,51 @@
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { MDXProvider } from "@mdx-js/react";
+import { MotionConfig } from "framer-motion";
+import { App } from "./App";
+import { queryClient } from "./api";
+import { mdxComponents } from "./mdx-components";
+import { ToastStack } from "./ui/Toast";
+import { shellInfo, type Route } from "./router";
+
+function parseInitialRoute(): Route {
+	const fallback: Route = { kind: "notfound", path: location.pathname };
+	const el = document.getElementById("__mdxserve_route");
+	if (!el?.textContent) return fallback;
+	const rootCount = Number.parseInt(el.dataset.rootCount ?? "", 10);
+	if (Number.isFinite(rootCount)) shellInfo.rootCount = rootCount;
+	shellInfo.sameMachine = el.dataset.sameMachine === "1";
+	try {
+		return JSON.parse(el.textContent) as Route;
+	} catch {
+		return fallback;
+	}
+}
+
+function main() {
+	const rootEl = document.getElementById("root");
+	if (!rootEl) return;
+
+	// Reuse the root across HMR re-executions of this module (self-accepting
+	// below) instead of calling createRoot twice on the same container.
+	const globalWindow = window as Window & { __mdxserveRoot?: Root };
+	const root = (globalWindow.__mdxserveRoot ??= createRoot(rootEl));
+	const initialRoute = parseInitialRoute();
+
+	root.render(
+		<QueryClientProvider client={queryClient}>
+			<MotionConfig reducedMotion="user">
+				<MDXProvider components={mdxComponents}>
+					<App initialRoute={initialRoute} />
+				</MDXProvider>
+				<ToastStack />
+			</MotionConfig>
+		</QueryClientProvider>,
+	);
+}
+
+main();
+
+if (import.meta.hot) {
+	import.meta.hot.accept();
+}

package/client/export-doc.ts

@@ -0,0 +1,80 @@
+import type { inferRouterOutputs } from "@trpc/server";
+// Type-only: client/ may only import types from src/ (see client/api.ts).
+import type { AppRouter } from "../src/api/router";
+import type { ExportFormat } from "../src/export/service";
+import { trpcClient } from "./api";
+import { formatSize } from "./format";
+import { pushToast } from "./ui/Toast";
+import {
+	canUseSavePicker,
+	decodeContents,
+	downloadViaAnchor,
+	gestureStillActive,
+	pickSaveFile,
+	writeToHandle,
+} from "./export-save";
+
+type ExportDocResult = inferRouterOutputs<AppRouter>["exportDoc"];
+
+type Picked = { kind: "picked"; handle: FileSystemFileHandle | null } | { kind: "expired" };
+
+/**
+ * The viewer's Export flow: build on the server, then hand the bytes to the
+ * browser. The native save picker needs a live user gesture, and Chrome
+ * expires one about 5 s after the click — so it is only tried when the build
+ * finished inside that window; otherwise (and on Firefox/Safari, which have
+ * no picker) the file goes out as an ordinary download. Never picker-before-
+ * build: the picker truncates an existing file the moment it is chosen, and
+ * a failed build would leave that file empty.
+ */
+export async function exportDocFromViewer(input: {
+	path: string;
+	format: ExportFormat;
+}): Promise<void> {
+	let result: ExportDocResult;
+	try {
+		result = await trpcClient.exportDoc.mutate({ path: input.path, format: input.format });
+	} catch (error) {
+		console.error(error);
+		pushToast({ tone: "danger", text: "Export failed" });
+		return;
+	}
+
+	const blob = decodeContents(result.contents, result.encoding);
+	try {
+		if (canUseSavePicker() && gestureStillActive()) {
+			const picked: Picked = await pickSaveFile(result.fileName, input.format).then(
+				(handle) => ({ kind: "picked", handle }),
+				// SecurityError: the gesture expired between the check and the
+				// call. A plain download needs no gesture.
+				() => ({ kind: "expired" }),
+			);
+			if (picked.kind === "picked") {
+				// The reader closed the picker: nothing was saved, nothing to say.
+				if (!picked.handle) return;
+				await writeToHandle(picked.handle, blob);
+			} else {
+				downloadViaAnchor(result.fileName, blob);
+			}
+		} else {
+			downloadViaAnchor(result.fileName, blob);
+		}
+	} catch (error) {
+		console.error(error);
+		pushToast({ tone: "danger", text: "Couldn't save the file" });
+		return;
+	}
+
+	pushToast({
+		tone: "ok",
+		icon: "download",
+		text: `Exported ${result.fileName} · ${formatSize(result.bytes)}`,
+	});
+	if (result.warnings.length > 0) {
+		console.warn(result.warnings.join("\n"));
+		pushToast({
+			tone: "warn",
+			text: `${result.warnings.length} export warning${result.warnings.length === 1 ? "" : "s"}`,
+		});
+	}
+}

package/client/export-save.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure(ish) helpers behind the Export dialog's save flow (client/ui/ExportDialog.tsx).
+ * Nothing here touches `window`/`document`/`navigator` at module scope, so this
+ * module stays importable under node — the file-name/encoding logic is unit
+ * tested the same way client/mermaid-direction.ts is.
+ */
+
+/**
+ * `/a/b/guide.md` -> `guide.html`; handles `\` separators, a case-insensitive
+ * `.md`/`.mdx` source extension, and a stray trailing `.<extension>` (so
+ * re-running this on its own previous output — e.g. re-exporting the same
+ * doc — never doubles the extension).
+ */
+export function exportFileName(docPath: string, extension: string): string {
+	const lastSegment = docPath.split(/[/\\]/).pop() ?? docPath;
+	const targetExtensionPattern = extension.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const stem = lastSegment
+		.replace(/\.mdx?$/i, "")
+		.replace(new RegExp(`\\.${targetExtensionPattern}$`, "i"), "");
+	return `${stem}.${extension}`;
+}
+
+const MIME_TYPES: Record<string, string> = {
+	html: "text/html",
+};
+
+/** "html" -> "text/html"; any other extension falls back to a generic binary type. */
+export function mimeFor(extension: string): string {
+	return MIME_TYPES[extension] ?? "application/octet-stream";
+}
+
+/** Decodes `exportDoc`'s wire contents (utf8 text or base64 bytes) into a Blob. */
+export function decodeContents(contents: string, encoding: "utf8" | "base64"): Blob {
+	if (encoding === "utf8") return new Blob([contents], { type: "text/plain" });
+	const binary = atob(contents);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return new Blob([bytes]);
+}
+
+/** Whether the browser exposes the File System Access save-picker API. */
+export function canUseSavePicker(): boolean {
+	return typeof window !== "undefined" && "showSaveFilePicker" in window;
+}
+
+/** Whether a user gesture (click) is still active — the picker requires one. */
+export function gestureStillActive(): boolean {
+	return navigator.userActivation?.isActive ?? false;
+}
+
+/**
+ * Opens the native save-file picker; resolves `null` when the user cancels
+ * (the picker rejects with `AbortError`). Must be called while a user gesture
+ * is still active, or the browser rejects with a `SecurityError`.
+ */
+export async function pickSaveFile(
+	suggestedName: string,
+	extension: string,
+): Promise<FileSystemFileHandle | null> {
+	if (!window.showSaveFilePicker) return null;
+	try {
+		return await window.showSaveFilePicker({
+			suggestedName,
+			types: [
+				{
+					description: extension.toUpperCase(),
+					accept: { [mimeFor(extension)]: [`.${extension}`] },
+				},
+			],
+		});
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "AbortError") return null;
+		throw error;
+	}
+}
+
+/** Writes `blob` to a handle from `pickSaveFile` and closes the stream. */
+export async function writeToHandle(handle: FileSystemFileHandle, blob: Blob): Promise<void> {
+	const writable = await handle.createWritable();
+	await writable.write(blob);
+	await writable.close();
+}
+
+/** Firefox/Safari fallback: a hidden `<a download>` click, then revoke the object URL. */
+export function downloadViaAnchor(fileName: string, blob: Blob): void {
+	const url = URL.createObjectURL(blob);
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = fileName;
+	document.body.appendChild(anchor);
+	anchor.click();
+	anchor.remove();
+	// Revoke after the click has been dispatched; some browsers start the
+	// download asynchronously and would find the URL already gone.
+	setTimeout(() => URL.revokeObjectURL(url), 0);
+}

package/client/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#111827"/><text x="16" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="15" font-weight="700" fill="#f9fafb">M↓</text></svg>