cantip 0.1.0

package/app/components/ui/dropdown-menu.tsx

@@ -0,0 +1,156 @@
+import { createContext, useContext, useEffect, useId, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+
+import { cn } from '~/lib/utils'
+
+/**
+ * Lightweight dropdown menu — no extra dependency, mirrors the hand-rolled
+ * pattern used across the app (ProjectSwitcher, Sidebar RowMenu). A trigger
+ * button toggles a menu rendered in a portal with fixed positioning computed
+ * from the trigger rect, so it's never clipped by an ancestor's `overflow`.
+ *
+ * Closes on outside click, Escape, scroll, or resize. The menu is anchored to a
+ * corner of the trigger via `align`:
+ *   - 'start' : menu's left edge aligns with the trigger's left edge
+ *   - 'end'   : menu's right edge aligns with the trigger's right edge
+ *
+ * Compose menu contents with <DropdownMenuItem>. `onSelect` fires then the menu
+ * closes automatically.
+ */
+
+interface MenuPos {
+	top: number
+	/** The CSS `left` for the menu box; combined with `translateX` for `end` align. */
+	left: number
+	align: 'start' | 'end'
+}
+
+/** Lets a <DropdownMenuItem> close its own parent menu after selecting. */
+const MenuCloseContext = createContext<() => void>(() => {})
+
+export function DropdownMenu({
+	trigger,
+	children,
+	align = 'start',
+	menuClassName,
+	className,
+	label,
+}: {
+	/** Render the trigger; receives the live open state for styling. */
+	trigger: (state: { open: boolean }) => React.ReactNode
+	children: React.ReactNode
+	align?: 'start' | 'end'
+	/** Extra classes for the menu box. */
+	menuClassName?: string
+	/** Classes for the trigger button; a function receives the live open state. */
+	className?: string | ((state: { open: boolean }) => string)
+	/** Accessible label for the trigger button. */
+	label?: string
+}) {
+	const [open, setOpen] = useState(false)
+	const [pos, setPos] = useState<MenuPos | null>(null)
+	const btnRef = useRef<HTMLButtonElement>(null)
+	const menuId = useId()
+
+	useEffect(() => {
+		if (!open) return
+		const close = () => setOpen(false)
+		const onKey = (e: KeyboardEvent) => {
+			if (e.key === 'Escape') setOpen(false)
+		}
+		// Close on any outside interaction; also on scroll/resize, since the fixed
+		// menu would otherwise drift away from its (scrolled) trigger.
+		document.addEventListener('mousedown', close)
+		document.addEventListener('keydown', onKey)
+		window.addEventListener('scroll', close, true)
+		window.addEventListener('resize', close)
+		return () => {
+			document.removeEventListener('mousedown', close)
+			document.removeEventListener('keydown', onKey)
+			window.removeEventListener('scroll', close, true)
+			window.removeEventListener('resize', close)
+		}
+	}, [open])
+
+	const toggle = (e: React.MouseEvent) => {
+		// Don't let an ancestor's onClick (e.g. a row navigation) fire too.
+		e.stopPropagation()
+		e.preventDefault()
+		if (!open && btnRef.current) {
+			const r = btnRef.current.getBoundingClientRect()
+			setPos({ top: r.bottom + 4, left: align === 'end' ? r.right : r.left, align })
+		}
+		setOpen((o) => !o)
+	}
+
+	return (
+		<>
+			<button
+				ref={btnRef}
+				type="button"
+				aria-haspopup="menu"
+				aria-expanded={open}
+				aria-controls={open ? menuId : undefined}
+				aria-label={label}
+				onClick={toggle}
+				className={typeof className === 'function' ? className({ open }) : className}
+			>
+				{trigger({ open })}
+			</button>
+			{open &&
+				pos &&
+				createPortal(
+					<div
+						id={menuId}
+						role="menu"
+						// Block the document mousedown-to-close for clicks inside the menu.
+						onMouseDown={(e) => e.stopPropagation()}
+						onClick={(e) => e.stopPropagation()}
+						style={{
+							position: 'fixed',
+							top: pos.top,
+							left: pos.left,
+							transform: pos.align === 'end' ? 'translateX(-100%)' : undefined,
+						}}
+						className={cn(
+							'z-[200] min-w-[12rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md',
+							menuClassName,
+						)}
+					>
+						<MenuCloseContext.Provider value={() => setOpen(false)}>
+							{children}
+						</MenuCloseContext.Provider>
+					</div>,
+					document.body,
+				)}
+		</>
+	)
+}
+
+export function DropdownMenuItem({
+	onSelect,
+	children,
+	className,
+}: {
+	onSelect: () => void
+	children: React.ReactNode
+	className?: string
+}) {
+	const close = useContext(MenuCloseContext)
+	return (
+		<button
+			type="button"
+			role="menuitem"
+			onClick={() => {
+				close()
+				onSelect()
+			}}
+			className={cn(
+				'flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm transition-colors hover:bg-sidebar-accent',
+				className,
+			)}
+		>
+			{children}
+		</button>
+	)
+}

package/app/components/ui/input.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react'
+
+import { cn } from '~/lib/utils'
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<input
+			type={type}
+			data-slot="input"
+			className={cn(
+				'file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+				'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+				'aria-invalid:ring-destructive/20 aria-invalid:border-destructive',
+				className,
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Input }

package/app/entry.client.tsx

@@ -0,0 +1,12 @@
+import { RemixBrowser } from "@remix-run/react";
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <RemixBrowser />
+    </StrictMode>
+  );
+});

package/app/entry.server.tsx

@@ -0,0 +1,155 @@
+import { PassThrough } from "node:stream";
+
+import type { AppLoadContext, EntryContext } from "@remix-run/node";
+import { createReadableStreamFromReadable } from "@remix-run/node";
+import { RemixServer } from "@remix-run/react";
+import * as isbotModule from "isbot";
+import { renderToPipeableStream } from "react-dom/server";
+
+const ABORT_DELAY = 5_000;
+
+export default function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  remixContext: EntryContext,
+  loadContext: AppLoadContext
+) {
+  let prohibitOutOfOrderStreaming =
+    isBotRequest(request.headers.get("user-agent")) || remixContext.isSpaMode;
+
+  return prohibitOutOfOrderStreaming
+    ? handleBotRequest(
+        request,
+        responseStatusCode,
+        responseHeaders,
+        remixContext
+      )
+    : handleBrowserRequest(
+        request,
+        responseStatusCode,
+        responseHeaders,
+        remixContext
+      );
+}
+
+// We have some Remix apps in the wild already running with isbot@3 so we need
+// to maintain backwards compatibility even though we want new apps to use
+// isbot@4.  That way, we can ship this as a minor Semver update to @remix-run/dev.
+function isBotRequest(userAgent: string | null) {
+  if (!userAgent) {
+    return false;
+  }
+
+  // isbot >= 3.8.0, >4
+  if ("isbot" in isbotModule && typeof isbotModule.isbot === "function") {
+    return isbotModule.isbot(userAgent);
+  }
+
+  // isbot < 3.8.0
+  if ("default" in isbotModule && typeof isbotModule.default === "function") {
+    return isbotModule.default(userAgent);
+  }
+
+  return false;
+}
+
+function handleBotRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  remixContext: EntryContext
+) {
+  return new Promise((resolve, reject) => {
+    let shellRendered = false;
+    const { pipe, abort } = renderToPipeableStream(
+      <RemixServer
+        context={remixContext}
+        url={request.url}
+        abortDelay={ABORT_DELAY}
+      />,
+      {
+        onAllReady() {
+          shellRendered = true;
+          const body = new PassThrough();
+          const stream = createReadableStreamFromReadable(body);
+
+          responseHeaders.set("Content-Type", "text/html");
+
+          resolve(
+            new Response(stream, {
+              headers: responseHeaders,
+              status: responseStatusCode,
+            })
+          );
+
+          pipe(body);
+        },
+        onShellError(error: unknown) {
+          reject(error);
+        },
+        onError(error: unknown) {
+          responseStatusCode = 500;
+          // Log streaming rendering errors from inside the shell.  Don't log
+          // errors encountered during initial shell rendering since they'll
+          // reject and get logged in handleDocumentRequest.
+          if (shellRendered) {
+            console.error(error);
+          }
+        },
+      }
+    );
+
+    setTimeout(abort, ABORT_DELAY);
+  });
+}
+
+function handleBrowserRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  remixContext: EntryContext
+) {
+  return new Promise((resolve, reject) => {
+    let shellRendered = false;
+    const { pipe, abort } = renderToPipeableStream(
+      <RemixServer
+        context={remixContext}
+        url={request.url}
+        abortDelay={ABORT_DELAY}
+      />,
+      {
+        onShellReady() {
+          shellRendered = true;
+          const body = new PassThrough();
+          const stream = createReadableStreamFromReadable(body);
+
+          responseHeaders.set("Content-Type", "text/html");
+
+          resolve(
+            new Response(stream, {
+              headers: responseHeaders,
+              status: responseStatusCode,
+            })
+          );
+
+          pipe(body);
+        },
+        onShellError(error: unknown) {
+          reject(error);
+        },
+        onError(error: unknown) {
+          responseStatusCode = 500;
+          // Log streaming rendering errors from inside the shell.  Don't log
+          // errors encountered during initial shell rendering since they'll
+          // reject and get logged in handleDocumentRequest.
+          if (shellRendered) {
+            console.error(error);
+          }
+        },
+      }
+    );
+
+    setTimeout(abort, ABORT_DELAY);
+  });
+}

package/app/generated/site.ts

@@ -0,0 +1,19 @@
+// AUTO-GENERATED by scripts/generate-content.ts — DO NOT EDIT.
+// Seed (empty site) committed so the engine typechecks before any generate. At
+// RUNTIME the Vite `~/generated/*` alias redirects to the user's cwd, so this
+// engine copy is only the type/seed fallback — the user's generated site.ts wins.
+import type { GeneratedSite } from '~/lib/config/site'
+
+export const SITE: GeneratedSite = {
+	site: {
+		title: 'Docs',
+		description: '',
+		lang: 'ru',
+		favicon: '/favicon.svg',
+		logo: { light: '/logo-light.svg', dark: '/logo-dark.svg' },
+		defaultTheme: 'dark',
+	},
+	projects: [],
+	general: { enabled: false, id: 'general', name: 'Без проекта', logo: '/projects/general.svg', description: '' },
+	ui: {},
+}

package/app/generated/slots.ts

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by scripts/generate-content.ts — DO NOT EDIT.
+// Seed: every slot null (= engine default). `generate` rewrites this from the
+// `components` overrides in docs.config.ts. Committed so a fresh checkout builds
+// before the first generate. See app/lib/slots.tsx for the slot contract.
+import type { ComponentType } from 'react'
+
+export const Home: ComponentType<any> | null = null
+export const DocPage: ComponentType<any> | null = null
+export const TopBar: ComponentType<any> | null = null
+export const Toc: ComponentType<any> | null = null

package/app/generated/theme.generated.css

@@ -0,0 +1,60 @@
+/* AUTO-GENERATED by scripts/generate-content.ts from docs.config.ts theme. DO NOT EDIT. */
+:root {
+	--brand: oklch(0.42 0.158 286);
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.145 0 0);
+	--card: oklch(1 0 0);
+	--card-foreground: oklch(0.145 0 0);
+	--popover: oklch(1 0 0);
+	--popover-foreground: oklch(0.145 0 0);
+	--primary: var(--brand);
+	--primary-foreground: oklch(0.985 0 0);
+	--secondary: oklch(0.97 0 0);
+	--secondary-foreground: oklch(0.205 0 0);
+	--muted: oklch(0.97 0 0);
+	--muted-foreground: oklch(0.556 0 0);
+	--accent: oklch(0.97 0 0);
+	--accent-foreground: oklch(0.205 0 0);
+	--destructive: oklch(0.577 0.245 27.325);
+	--border: oklch(0.922 0 0);
+	--input: oklch(0.922 0 0);
+	--ring: oklch(0.708 0 0);
+	--sidebar: oklch(0.985 0 0);
+	--sidebar-foreground: oklch(0.145 0 0);
+	--sidebar-primary: oklch(0.205 0 0);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.97 0 0);
+	--sidebar-accent-foreground: oklch(0.205 0 0);
+	--sidebar-border: oklch(0.922 0 0);
+	--sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+	--brand: oklch(0.68 0.14 286);
+	--background: oklch(0.145 0 0);
+	--foreground: oklch(0.985 0 0);
+	--card: oklch(0.205 0 0);
+	--card-foreground: oklch(0.985 0 0);
+	--popover: oklch(0.205 0 0);
+	--popover-foreground: oklch(0.985 0 0);
+	--primary: var(--brand);
+	--primary-foreground: oklch(0.205 0 0);
+	--secondary: oklch(0.269 0 0);
+	--secondary-foreground: oklch(0.985 0 0);
+	--muted: oklch(0.269 0 0);
+	--muted-foreground: oklch(0.708 0 0);
+	--accent: oklch(0.269 0 0);
+	--accent-foreground: oklch(0.985 0 0);
+	--destructive: oklch(0.704 0.191 22.216);
+	--border: oklch(1 0 0 / 10%);
+	--input: oklch(1 0 0 / 15%);
+	--ring: oklch(0.556 0 0);
+	--sidebar: oklch(0.205 0 0);
+	--sidebar-foreground: oklch(0.985 0 0);
+	--sidebar-primary: oklch(0.488 0.243 264.376);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.269 0 0);
+	--sidebar-accent-foreground: oklch(0.985 0 0);
+	--sidebar-border: oklch(1 0 0 / 10%);
+	--sidebar-ring: oklch(0.556 0 0);
+}

package/app/lib/config/config.server.ts

@@ -0,0 +1,50 @@
+/**
+ * App-side config reader (runtime).
+ *
+ * Reads the RESOLVED config that the build pipeline serialized to
+ * `app/generated/config.json` (under the user's cwd — same contract as the doc
+ * manifest in `content.server.ts`). It never imports the user's TS config, so it
+ * is safe to bundle into the Remix server.
+ *
+ * Read is synchronous + process-cached: `getConfig()` is called in server render
+ * paths (loaders, `projects.ts` helpers) where async would be awkward, and the
+ * config is tiny and immutable for the process lifetime.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { docsConfigSchema, type DocsConfig } from './schema'
+import { DEFAULT_THEME, defaultUiFor } from './defaults'
+
+const CONFIG_PATH = path.join(process.cwd(), 'app', 'generated', 'config.json')
+
+let cache: DocsConfig | null = null
+
+/** A fully-defaulted empty config, used when no config.json has been generated. */
+function emptyConfig(): DocsConfig {
+	const parsed = docsConfigSchema.parse({})
+	return {
+		...parsed,
+		theme: { colors: { light: { ...DEFAULT_THEME.light }, dark: { ...DEFAULT_THEME.dark } } },
+		ui: { ...defaultUiFor(parsed.site.lang) },
+	}
+}
+
+/** The resolved docs config for this site (process-cached). */
+export function getConfig(): DocsConfig {
+	if (cache) return cache
+	try {
+		const raw = fs.readFileSync(CONFIG_PATH, 'utf8')
+		// Already resolved + validated at generate time; re-parse defensively so a
+		// hand-edited file still can't violate the schema at runtime.
+		cache = docsConfigSchema.parse(JSON.parse(raw))
+	} catch {
+		cache = emptyConfig()
+	}
+	return cache
+}
+
+/** Resolved UI strings for the current site (lang-defaulted, user-overridden). */
+export function getUi(): Record<string, string> {
+	return getConfig().ui
+}

package/app/lib/config/defaults.ts

@@ -0,0 +1,120 @@
+/**
+ * Shipped defaults: theme tokens + per-locale UI strings.
+ *
+ * These reproduce this project's ORIGINAL hardcoded values, so a config that
+ * omits `theme`/`ui` (or omits individual keys) renders byte-for-byte as before.
+ * `loadConfig` merges authored values over these.
+ *
+ * UI strings are keyed by `site.lang`. Only the chrome strings users typically
+ * want to rebrand are externalized here; the keyboard-shortcut cheatsheet labels
+ * (`useKeyboardShortcuts.ts`) remain in code as an advanced concern.
+ */
+
+/** Default OKLCH theme tokens — mirror of `app/styles/tailwind.css` :root/.dark. */
+export const DEFAULT_THEME = {
+	light: {
+		'--brand': 'oklch(0.42 0.158 286)',
+		'--background': 'oklch(1 0 0)',
+		'--foreground': 'oklch(0.145 0 0)',
+		'--card': 'oklch(1 0 0)',
+		'--card-foreground': 'oklch(0.145 0 0)',
+		'--popover': 'oklch(1 0 0)',
+		'--popover-foreground': 'oklch(0.145 0 0)',
+		'--primary': 'var(--brand)',
+		'--primary-foreground': 'oklch(0.985 0 0)',
+		'--secondary': 'oklch(0.97 0 0)',
+		'--secondary-foreground': 'oklch(0.205 0 0)',
+		'--muted': 'oklch(0.97 0 0)',
+		'--muted-foreground': 'oklch(0.556 0 0)',
+		'--accent': 'oklch(0.97 0 0)',
+		'--accent-foreground': 'oklch(0.205 0 0)',
+		'--destructive': 'oklch(0.577 0.245 27.325)',
+		'--border': 'oklch(0.922 0 0)',
+		'--input': 'oklch(0.922 0 0)',
+		'--ring': 'oklch(0.708 0 0)',
+		'--sidebar': 'oklch(0.985 0 0)',
+		'--sidebar-foreground': 'oklch(0.145 0 0)',
+		'--sidebar-primary': 'oklch(0.205 0 0)',
+		'--sidebar-primary-foreground': 'oklch(0.985 0 0)',
+		'--sidebar-accent': 'oklch(0.97 0 0)',
+		'--sidebar-accent-foreground': 'oklch(0.205 0 0)',
+		'--sidebar-border': 'oklch(0.922 0 0)',
+		'--sidebar-ring': 'oklch(0.708 0 0)',
+	} as Record<string, string>,
+	dark: {
+		'--brand': 'oklch(0.68 0.14 286)',
+		'--background': 'oklch(0.145 0 0)',
+		'--foreground': 'oklch(0.985 0 0)',
+		'--card': 'oklch(0.205 0 0)',
+		'--card-foreground': 'oklch(0.985 0 0)',
+		'--popover': 'oklch(0.205 0 0)',
+		'--popover-foreground': 'oklch(0.985 0 0)',
+		'--primary': 'var(--brand)',
+		'--primary-foreground': 'oklch(0.205 0 0)',
+		'--secondary': 'oklch(0.269 0 0)',
+		'--secondary-foreground': 'oklch(0.985 0 0)',
+		'--muted': 'oklch(0.269 0 0)',
+		'--muted-foreground': 'oklch(0.708 0 0)',
+		'--accent': 'oklch(0.269 0 0)',
+		'--accent-foreground': 'oklch(0.985 0 0)',
+		'--destructive': 'oklch(0.704 0.191 22.216)',
+		'--border': 'oklch(1 0 0 / 10%)',
+		'--input': 'oklch(1 0 0 / 15%)',
+		'--ring': 'oklch(0.556 0 0)',
+		'--sidebar': 'oklch(0.205 0 0)',
+		'--sidebar-foreground': 'oklch(0.985 0 0)',
+		'--sidebar-primary': 'oklch(0.488 0.243 264.376)',
+		'--sidebar-primary-foreground': 'oklch(0.985 0 0)',
+		'--sidebar-accent': 'oklch(0.269 0 0)',
+		'--sidebar-accent-foreground': 'oklch(0.985 0 0)',
+		'--sidebar-border': 'oklch(1 0 0 / 10%)',
+		'--sidebar-ring': 'oklch(0.556 0 0)',
+	} as Record<string, string>,
+}
+
+/**
+ * The UI string catalogue. Keys are stable identifiers used in components via
+ * `getUi(config)`; values are the originals (ru). `en` is a best-effort fallback
+ * for non-ru sites so an unset `ui` doesn't render Russian on an English site.
+ */
+export const UI_STRINGS: Record<string, Record<string, string>> = {
+	ru: {
+		projects: 'Проекты',
+		selectProject: 'Выберите проект',
+		noProject: 'Без проекта',
+		onThisPage: 'На этой странице',
+		properties: 'Свойства',
+		shortcuts: 'Горячие клавиши',
+		searchProjectFilter: 'Проект',
+		close: 'Закрыть',
+		closePanel: 'Закрыть панель',
+		closeSearch: 'Закрыть поиск',
+		closeTab: 'Закрыть вкладку',
+		home: 'Главная',
+		files: 'Файлы',
+		search: 'Поиск',
+		toggleTheme: 'Переключить тему',
+	},
+	en: {
+		projects: 'Projects',
+		selectProject: 'Select a project',
+		noProject: 'No project',
+		onThisPage: 'On this page',
+		properties: 'Properties',
+		shortcuts: 'Keyboard shortcuts',
+		searchProjectFilter: 'Project',
+		close: 'Close',
+		closePanel: 'Close panel',
+		closeSearch: 'Close search',
+		closeTab: 'Close tab',
+		home: 'Home',
+		files: 'Files',
+		search: 'Search',
+		toggleTheme: 'Toggle theme',
+	},
+}
+
+/** UI strings for a language, falling back to `en` then `ru`. */
+export function defaultUiFor(lang: string): Record<string, string> {
+	return UI_STRINGS[lang] ?? UI_STRINGS.en ?? UI_STRINGS.ru
+}

package/app/lib/config/load.ts

@@ -0,0 +1,82 @@
+/**
+ * Build-side config loader (Node only — imports the user's TS config).
+ *
+ * Runs from the build pipeline (`scripts/*`), which executes under
+ * `node --experimental-strip-types`, so it can `import()` the user's
+ * `docs.config.ts` directly. It validates against `docsConfigSchema`, merges the
+ * shipped theme/ui defaults, fills per-project derived defaults (logo, landing),
+ * and returns a fully-resolved `DocsConfig`.
+ *
+ * The running APP must NOT call this (Vite can't bundle the user's cwd TS file);
+ * the generator serializes the resolved config to `app/generated/config.json`,
+ * and the app reads that JSON at runtime via `config.server.ts`. This module is
+ * the single place the TS config is ever imported.
+ */
+import { pathToFileURL } from 'node:url'
+import path from 'node:path'
+import fs from 'node:fs'
+
+import { docsConfigSchema, type DocsConfig } from './schema.ts'
+import { DEFAULT_THEME, defaultUiFor } from './defaults.ts'
+
+/** Candidate config filenames, in resolution order, relative to cwd. */
+const CONFIG_NAMES = ['docs.config.ts', 'docs.config.js', 'docs.config.mjs']
+
+/** Locate the user's config file in `cwd`, or null when none exists. */
+function findConfigFile(cwd: string): string | null {
+	for (const name of CONFIG_NAMES) {
+		const p = path.join(cwd, name)
+		if (fs.existsSync(p)) return p
+	}
+	return null
+}
+
+/**
+ * Load + validate + fully resolve the docs config from `cwd` (defaults to
+ * `process.cwd()`). With no config file, returns an all-defaults config so the
+ * engine still runs (empty site, no projects) rather than throwing.
+ */
+export async function loadConfig(cwd: string = process.cwd()): Promise<DocsConfig> {
+	const file = findConfigFile(cwd)
+	let authored: unknown = {}
+	if (file) {
+		// Cache-bust with the file mtime so repeated loads in one watch session
+		// pick up edits (import() caches by URL otherwise).
+		const mtime = fs.statSync(file).mtimeMs
+		const mod = await import(`${pathToFileURL(file).href}?t=${mtime}`)
+		authored = mod.default ?? mod.config ?? mod
+	}
+
+	const parsed = docsConfigSchema.safeParse(authored)
+	if (!parsed.success) {
+		throw new Error(
+			`Invalid docs.config:\n\n${JSON.stringify(parsed.error.format(), null, 2)}`,
+		)
+	}
+	return resolveDerived(parsed.data)
+}
+
+/**
+ * Fill values that depend on other fields and merge shipped defaults:
+ * - per-project `logo` → `/projects/<id>.svg`, `landing` → first-doc URL (left
+ *   null here; the app derives it from the manifest when unset),
+ * - theme colors merged OVER `DEFAULT_THEME`,
+ * - `ui` merged OVER the per-`lang` default strings.
+ */
+function resolveDerived(config: DocsConfig): DocsConfig {
+	const projects = config.projects.map((p) => ({
+		...p,
+		logo: p.logo ?? `/projects/${p.id}.svg`,
+	}))
+
+	const theme = {
+		colors: {
+			light: { ...DEFAULT_THEME.light, ...config.theme.colors.light },
+			dark: { ...DEFAULT_THEME.dark, ...config.theme.colors.dark },
+		},
+	}
+
+	const ui = { ...defaultUiFor(config.site.lang), ...config.ui }
+
+	return { ...config, projects, theme, ui }
+}