docula 2.0.0 → 2.1.0

package/dist/docula.js

@@ -9,11 +9,15 @@ import { Ecto } from "ecto";
 import { Hashery } from "hashery";
 import { Writr, Writr as Writr$1 } from "writr";
 import { blue, bold, cyan, dim, gray, green, magenta, red, white, yellow } from "colorette";
+import { promises } from "node:dns";
+import net from "node:net";
+import ipaddr from "ipaddr.js";
+import { Agent, fetch } from "undici";
 import { CacheableNet } from "@cacheable/net";
 import os from "node:os";
 import sea from "node:sea";
 //#region package.json
-var version = "2.0.0";
+var version = "2.1.0";
 var package_default = {
 	name: "docula",
 	version,
@@ -28,7 +32,7 @@ var package_default = {
 		"url": "git+https://github.com/jaredwray/docula.git"
 	},
 	author: "Jared Wray <me@jaredwray.com>",
-	engines: { "node": "^22.18.0 || >=24.0.0" },
+	engines: { "node": "^22.19.0 || >=24.0.0" },
 	license: "MIT",
 	scripts: {
 		"clean": "rimraf ./dist ./coverage ./node_modules ./package-lock.json ./yarn.lock ./pnpm-lock.yaml ./site/dist",
@@ -70,32 +74,34 @@ var package_default = {
 	],
 	bin: { "docula": "./bin/docula.js" },
 	dependencies: {
-		"@ai-sdk/anthropic": "^3.0.77",
-		"@ai-sdk/google": "^3.0.72",
-		"@ai-sdk/openai": "^3.0.63",
-		"@cacheable/net": "^2.0.7",
-		"ai": "^6.0.178",
+		"@ai-sdk/anthropic": "^3.0.83",
+		"@ai-sdk/google": "^3.0.81",
+		"@ai-sdk/openai": "^3.0.70",
+		"@cacheable/net": "^2.0.8",
+		"ai": "^6.0.202",
 		"colorette": "^2.0.20",
-		"ecto": "^4.8.5",
-		"hashery": "^2.0.0",
+		"ecto": "^4.8.7",
+		"hashery": "^3.0.0",
+		"ipaddr.js": "2.4.0",
 		"jiti": "^2.7.0",
 		"serve-handler": "^6.1.7",
+		"undici": "8.4.1",
 		"update-notifier": "^7.3.1",
 		"writr": "^6.1.2"
 	},
 	devDependencies: {
-		"@biomejs/biome": "^2.4.15",
+		"@biomejs/biome": "^2.4.16",
 		"@playwright/test": "^1.60.0",
-		"@types/node": "^24.12.4",
+		"@types/node": "^24.13.2",
 		"@types/serve-handler": "^6.1.4",
 		"@types/update-notifier": "^6.0.8",
-		"@vitest/coverage-v8": "^4.1.6",
+		"@vitest/coverage-v8": "^4.1.8",
 		"dotenv": "^17.4.2",
 		"rimraf": "^6.1.3",
-		"tsdown": "^0.22.0",
-		"tsx": "^4.21.0",
+		"tsdown": "^0.22.2",
+		"tsx": "^4.22.4",
 		"typescript": "^6.0.3",
-		"vitest": "^4.1.6"
+		"vitest": "^4.1.8"
 	},
 	files: [
 		"dist",
@@ -304,7 +310,10 @@ function logChangelogMetadata(console, name, metadata, fromCache) {
 		return;
 	}
 	console.info(`AI enriched changelog: ${name}`);
-	if (metadata.preview || metadata.summary) console.log(white(`  preview: ${truncate(metadata.preview || metadata.summary || "")}`));
+	if (metadata.preview || metadata.summary) console.log(white(
+		/* v8 ignore next -- the enclosing `if` guarantees preview or summary is truthy, so the `|| ""` fallback is unreachable; it only satisfies truncate's string parameter type -- @preserve */
+		`  preview: ${truncate(metadata.preview || metadata.summary || "")}`
+	));
 	if (metadata.description) console.log(white(`  description: ${truncate(metadata.description)}`));
 	if (metadata.keywords?.length) console.log(white(`  keywords: ${truncate(metadata.keywords.join(", "))}`));
 }
@@ -884,6 +893,294 @@ async function buildRobotsPage(options) {
 	await (fs.existsSync(`${sitePath}/robots.txt`) ? fs.promises.copyFile(`${sitePath}/robots.txt`, robotsPath) : fs.promises.writeFile(robotsPath, "User-agent: *\nDisallow:"));
 }
 //#endregion
+//#region src/safe-fetch.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_REDIRECTS = 5;
+const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
+const MAX_URL_LENGTH = 8192;
+const BLOCKED_HOSTNAMES = new Set([
+	"localhost",
+	"ip6-localhost",
+	"ip6-loopback",
+	"localhost.localdomain"
+]);
+const BLOCKED_IPV4_RANGES = new Set([
+	"unspecified",
+	"broadcast",
+	"multicast",
+	"linkLocal",
+	"loopback",
+	"carrierGradeNat",
+	"private",
+	"reserved",
+	"as112",
+	"amt"
+]);
+const BLOCKED_IPV6_RANGES = new Set([
+	"unspecified",
+	"linkLocal",
+	"multicast",
+	"loopback",
+	"uniqueLocal",
+	"discard",
+	"rfc6145",
+	"rfc6052",
+	"teredo",
+	"benchmarking",
+	"amt",
+	"as112v6",
+	"reserved"
+]);
+var SsrfBlockedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SsrfBlockedError";
+	}
+};
+/**
+* Returns true if `ip` is NOT publicly routable.
+*
+* IPv4-mapped (`::ffff:a.b.c.d`), 6to4 (`2002:hh:hh::/16`), and the deprecated
+* IPv4-compatible (`::a.b.c.d`) IPv6 forms all unwrap to an embedded IPv4
+* address and are re-validated against the IPv4 rules. Writing a private IPv4
+* in any of these IPv6 spellings — including the hex form `::ffff:7f00:1` —
+* therefore does not bypass the IPv4 deny-list.
+*
+* Failure-closed: malformed input is treated as private.
+*/
+function isPrivateIp(ip) {
+	if (!ipaddr.isValid(ip)) return true;
+	const parsed = ipaddr.parse(ip);
+	if (parsed.kind() === "ipv4") return BLOCKED_IPV4_RANGES.has(parsed.range());
+	const v6 = parsed;
+	const range = v6.range();
+	if (range === "ipv4Mapped") return isPrivateIp(v6.toIPv4Address().toString());
+	if (range === "6to4") {
+		const parts = v6.parts;
+		/* v8 ignore stop */
+		return isPrivateIp(`${(parts[1] ?? 0) >> 8}.${(parts[1] ?? 0) & 255}.${(parts[2] ?? 0) >> 8}.${(parts[2] ?? 0) & 255}`);
+	}
+	if (range !== "unicast") return BLOCKED_IPV6_RANGES.has(range);
+	const parts = v6.parts;
+	if (parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0 && !(parts[6] === 0 && parts[7] === 0))
+ /* v8 ignore stop */
+	return isPrivateIp(`${(parts[6] ?? 0) >> 8}.${(parts[6] ?? 0) & 255}.${(parts[7] ?? 0) >> 8}.${(parts[7] ?? 0) & 255}`);
+	return false;
+}
+/**
+* Validates `url` and, for hostname-based URLs, resolves and validates every
+* returned IP. Throws SsrfBlockedError if the URL is unparseable, uses a
+* non-http(s) scheme, embeds credentials, targets a blocked hostname like
+* `localhost`, or resolves to any non-publicly-routable IP. Returns the
+* parsed URL and the validated addresses so the caller can pin them at
+* connect time and close the DNS-rebinding TOCTOU window.
+*/
+async function resolveAndValidate(url, options = {}) {
+	if (url.length > MAX_URL_LENGTH) throw new SsrfBlockedError(`URL exceeds ${MAX_URL_LENGTH} characters (got ${url.length})`);
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new SsrfBlockedError(`Invalid URL: ${url}`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new SsrfBlockedError(`Only http(s) URLs are allowed (got ${parsed.protocol})`);
+	if (parsed.username || parsed.password) throw new SsrfBlockedError("Refusing to fetch URL with embedded credentials");
+	const rawHostname = parsed.hostname;
+	/* v8 ignore next 3 -- @preserve */
+	if (!rawHostname) throw new SsrfBlockedError("URL has no hostname");
+	const hostname = rawHostname.startsWith("[") && rawHostname.endsWith("]") ? rawHostname.slice(1, -1) : rawHostname;
+	const lowerHost = hostname.toLowerCase();
+	if (BLOCKED_HOSTNAMES.has(lowerHost) || lowerHost.endsWith(".localhost") || lowerHost.endsWith(".localhost.localdomain")) throw new SsrfBlockedError(`Refusing to fetch from ${hostname}`);
+	if (net.isIP(hostname)) {
+		if (isPrivateIp(hostname)) throw new SsrfBlockedError(`Refusing to fetch from non-public IP ${hostname}`);
+		return {
+			urlObj: parsed,
+			resolved: [{
+				address: hostname,
+				family: net.isIPv6(hostname) ? 6 : 4
+			}]
+		};
+	}
+	/* v8 ignore next -- the `?? dns.lookup` default invokes real DNS; only reachable without an injected lookup -- @preserve */
+	const lookupFn = options.lookup ?? promises.lookup;
+	let addresses;
+	try {
+		addresses = await lookupFn(hostname, {
+			all: true,
+			verbatim: true
+		});
+	} catch (error) {
+		throw new SsrfBlockedError(`DNS lookup for ${hostname} failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (addresses.length === 0) throw new SsrfBlockedError(`DNS lookup for ${hostname} returned no addresses`);
+	for (const { address } of addresses) if (isPrivateIp(address)) throw new SsrfBlockedError(`Refusing to fetch from ${hostname} — resolves to non-public IP ${address}`);
+	return {
+		urlObj: parsed,
+		resolved: addresses.map((a) => ({
+			address: a.address,
+			family: a.family === 6 ? 6 : 4
+		}))
+	};
+}
+/**
+* Builds a `net.lookup`-shaped callback that always returns the pre-validated
+* `resolved` addresses, ignoring the hostname argument. Supports both call
+* signatures: when `opts.all` is truthy the callback receives the full array;
+* otherwise (the shape Node uses when `autoSelectFamily` is disabled) the
+* callback receives a single `address, family` pair.
+*/
+function pinnedLookup(resolved) {
+	return (_hostname, opts, callback) => {
+		if (opts.all) {
+			callback(null, resolved);
+			return;
+		}
+		const first = resolved[0];
+		/* v8 ignore next 4 -- resolved is non-empty by construction in safeFetch -- @preserve */
+		if (!first) {
+			callback(/* @__PURE__ */ new Error("No pinned address available"));
+			return;
+		}
+		callback(null, first.address, first.family);
+	};
+}
+/**
+* fetch wrapper hardened against SSRF:
+*  - Scheme allow-list (http/https), no embedded credentials, no localhost.
+*  - The resolved IP is pinned to undici's TCP connect via a custom Agent
+*    `lookup`, so fetch does not re-resolve the hostname. This closes the
+*    DNS-rebinding TOCTOU window between validation and connect. TLS SNI
+*    and certificate validation still use the original hostname because
+*    undici's connector passes `host: hostname` to `tls.connect` regardless
+*    of what `lookup` returns; if that internal contract changes in a future
+*    undici release, this wrapper's TLS-hostname guarantee will need to be
+*    re-checked.
+*  - Redirects are followed manually; each target is re-validated and the
+*    new connect is re-pinned. The previous hop's body is cancelled before
+*    moving on so the connection is released instead of being held open.
+*  - `timeoutMs` bounds the total wall-clock budget — the AbortController
+*    survives until the returned body is fully consumed (or errors), so a
+*    slow-drip body cannot bypass the deadline.
+*  - `maxBodyBytes` caps the response body up-front via `content-length`
+*    (when it parses cleanly as a decimal integer) and during streaming.
+*  - URLs over `MAX_URL_LENGTH` are rejected before parsing.
+*  - Per-hop Agents are `destroy()`ed (not gracefully `close()`d) on error
+*    or after the body is consumed, so a malicious server cannot leak
+*    sockets by holding a redirected body open.
+*/
+async function safeFetch(url, options = {}) {
+	const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const lookup = options.lookup;
+	const totalController = new AbortController();
+	const totalTimer = setTimeout(() => totalController.abort(), timeoutMs);
+	const dispatchers = [];
+	let cleaned = false;
+	const cleanup = () => {
+		if (cleaned) return;
+		cleaned = true;
+		clearTimeout(totalTimer);
+		for (const d of dispatchers)
+ /* v8 ignore next -- the .catch arrow only runs if undici Agent.destroy() rejects, which it does not in practice -- @preserve */
+		d.destroy().catch(() => {});
+	};
+	let currentUrl = url;
+	try {
+		for (let hop = 0; hop <= maxRedirects; hop++) {
+			const { resolved } = await resolveAndValidate(currentUrl, { lookup });
+			const dispatcher = new Agent({ connect: { lookup: pinnedLookup(resolved) } });
+			dispatchers.push(dispatcher);
+			const response = await fetchImpl(currentUrl, {
+				dispatcher,
+				redirect: "manual",
+				signal: totalController.signal
+			});
+			if (response.status >= 300 && response.status < 400) {
+				const location = response.headers.get("location");
+				if (location) {
+					await response.body?.cancel().catch(() => {});
+					/* v8 ignore next -- the .catch arrow only runs if undici Agent.destroy() rejects, which it does not in practice -- @preserve */
+					dispatcher.destroy().catch(() => {});
+					dispatchers.pop();
+					let nextUrl;
+					try {
+						nextUrl = new URL(location, currentUrl).toString();
+					} catch {
+						throw new SsrfBlockedError(`Invalid redirect Location header (${location}) from ${currentUrl}`);
+					}
+					currentUrl = nextUrl;
+					continue;
+				}
+				return capResponseBody(response, maxBodyBytes, cleanup);
+			}
+			return capResponseBody(response, maxBodyBytes, cleanup);
+		}
+		throw new SsrfBlockedError(`Too many redirects (>${maxRedirects}) starting at ${url}`);
+	} catch (error) {
+		cleanup();
+		throw error;
+	}
+}
+function capResponseBody(response, maxBytes, onDone) {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength && /^\d+$/.test(contentLength)) {
+		const n = Number.parseInt(contentLength, 10);
+		if (n > maxBytes) {
+			onDone();
+			throw new SsrfBlockedError(`Response body exceeds ${maxBytes} bytes (content-length: ${n})`);
+		}
+	}
+	if (!response.body) {
+		onDone();
+		return response;
+	}
+	const reader = response.body.getReader();
+	let received = 0;
+	let finalized = false;
+	const finalize = () => {
+		/* v8 ignore next -- double-call guard; each finalize caller settles the stream, so finalize cannot deterministically run twice -- @preserve */
+		if (finalized) return;
+		finalized = true;
+		onDone();
+	};
+	const cappedStream = new ReadableStream({
+		async pull(controller) {
+			try {
+				const { value, done } = await reader.read();
+				if (done) {
+					controller.close();
+					finalize();
+					return;
+				}
+				received += value.byteLength;
+				if (received > maxBytes) {
+					controller.error(new SsrfBlockedError(`Response body exceeds ${maxBytes} bytes (streamed)`));
+					reader.cancel().catch(() => {});
+					finalize();
+					return;
+				}
+				controller.enqueue(value);
+			} catch (error) {
+				controller.error(error);
+				finalize();
+			}
+			/* v8 ignore stop */
+		},
+		/* v8 ignore next 4 -- only invoked when the consumer cancels the body stream -- @preserve */
+		cancel() {
+			reader.cancel().catch(() => {});
+			finalize();
+		}
+	});
+	return new Response(cappedStream, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
+//#endregion
 //#region src/builder-api.ts
 const writrOptions$4 = {
 	throwOnEmitError: false,
@@ -913,8 +1210,10 @@ async function getSafeSiteOverrideFileContent(sitePath, fileName) {
 		realSitePath = await fs.promises.realpath(resolvedSitePath);
 		realCandidatePath = await fs.promises.realpath(candidatePath);
 	} catch {
+		/* v8 ignore next -- realpath only throws on ENOENT/race after a successful lstat; defensive -- @preserve */
 		return;
 	}
+	/* v8 ignore next 3 -- llms override uses a fixed single-component filename, so no intermediate symlink can make a regular file's realpath escape the (consistently resolved) site path; defensive TOCTOU guard -- @preserve */
 	if (!isPathWithinBasePath(realCandidatePath, realSitePath)) return;
 	return fs.promises.readFile(realCandidatePath, "utf8");
 }
@@ -950,6 +1249,7 @@ async function getSafeLocalOpenApiSpecForSpec(data, specUrl) {
 		realSitePath = await fs.promises.realpath(resolvedSitePath);
 		realLocalPath = await fs.promises.realpath(resolvedLocalPath);
 	} catch {
+		/* v8 ignore next -- realpath only throws on ENOENT/race after a successful lstat; defensive -- @preserve */
 		return;
 	}
 	if (!isPathWithinBasePath(realLocalPath, realSitePath)) return;
@@ -969,7 +1269,7 @@ async function parseAndRenderSpec(data, specUrl) {
 	const localSpec = await getSafeLocalOpenApiSpecForSpec(data, specUrl);
 	if (localSpec) apiSpec = parseOpenApiSpec(localSpec.content);
 	else if (isRemoteUrl(specUrl)) try {
-		apiSpec = parseOpenApiSpec(await (await fetch(specUrl)).text());
+		apiSpec = parseOpenApiSpec(await (await safeFetch(specUrl)).text());
 	} catch {}
 	/* v8 ignore next -- @preserve */
 	if (apiSpec) {
@@ -1024,6 +1324,7 @@ async function buildAllApiPages(ecto, data) {
 async function renderApiContent(ecto, data) {
 	const firstSpecUrl = data.openApiSpecs?.[0]?.url;
 	if (!firstSpecUrl || !data.templates?.api) throw new Error("No API template or openApiUrl found");
+	/* v8 ignore next -- a truthy firstSpecUrl guarantees a non-empty openApiSpecs, so the false branch is unreachable; the legacy fallback below stays for defense-in-depth -- @preserve */
 	if (data.openApiSpecs && data.openApiSpecs.length > 0) return renderCombinedApiContent(ecto, data);
 	/* v8 ignore start -- @preserve */
 	const swaggerSource = `${data.sitePath}/api/swagger.json`;
@@ -1034,7 +1335,7 @@ async function renderApiContent(ecto, data) {
 	const localSpec = await getSafeLocalOpenApiSpec(data);
 	if (localSpec) apiSpec = parseOpenApiSpec(localSpec.content);
 	else if (firstSpecUrl && isRemoteUrl(firstSpecUrl)) try {
-		apiSpec = parseOpenApiSpec(await (await fetch(firstSpecUrl)).text());
+		apiSpec = parseOpenApiSpec(await (await safeFetch(firstSpecUrl)).text());
 	} catch {}
 	if (apiSpec) {
 		apiSpec.info.description = new Writr$1(apiSpec.info.description, writrOptions$4).renderSync();
@@ -1120,6 +1421,7 @@ function hashOptions(hash, options) {
 		template: options.template,
 		templatePath: options.templatePath,
 		enableLlmsTxt: options.enableLlmsTxt,
+		enableSearch: options.enableSearch,
 		changelogPerPage: options.changelogPerPage,
 		enableReleaseChangelog: options.enableReleaseChangelog,
 		sections: options.sections,
@@ -2112,6 +2414,153 @@ async function generateLlmsFullContent(data) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/builder-search.ts
+/**
+* Name of the JSON search index written to the output root. The client-side
+* search script fetches this file (relative to {@link DoculaData.baseUrl}) to
+* power the search modal.
+*/
+const SEARCH_INDEX_FILENAME = "search-index.json";
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " ",
+	copy: "©",
+	reg: "®",
+	trade: "™",
+	hellip: "…",
+	mdash: "—",
+	ndash: "–",
+	lsquo: "‘",
+	rsquo: "’",
+	ldquo: "“",
+	rdquo: "”"
+};
+const ENTITY_REGEX = /&(#[xX]?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g;
+const HEADING_REGEX = /<h([1-6])\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/h\1>/gi;
+/**
+* Decode the small set of HTML entities that can appear in rendered markdown
+* (named, decimal, and hexadecimal). Unknown named entities are left intact.
+*/
+function decodeEntities(text) {
+	return text.replace(ENTITY_REGEX, (match, entity) => {
+		if (entity[0] === "#") {
+			const codePoint = entity[1] === "x" || entity[1] === "X" ? Number.parseInt(entity.slice(2), 16) : Number.parseInt(entity.slice(1), 10);
+			if (Number.isNaN(codePoint)) return match;
+			try {
+				return String.fromCodePoint(codePoint);
+			} catch {
+				return match;
+			}
+		}
+		return NAMED_ENTITIES[entity.toLowerCase()] ?? match;
+	});
+}
+/**
+* Convert an HTML fragment into collapsed, decoded plain text. Script and
+* style blocks are dropped entirely before tags are stripped.
+*/
+function stripHtml(html) {
+	if (!html) return "";
+	return decodeEntities(html.replace(/<!--[\s\S]*?-->/g, " ").replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ").replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ").replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+}
+/**
+* Remove a trailing `index.html` so urls point at the clean directory path
+* that the static site actually serves.
+*/
+function stripIndexHtml(urlPath) {
+	return urlPath.replace(/index\.html$/, "");
+}
+function isTableOfContents(anchor, title) {
+	return anchor === "table-of-contents" || title.trim().toLowerCase() === "table of contents";
+}
+/**
+* Split a rendered HTML page into search records: one for the page intro
+* (content before the first heading) plus one per heading section. The
+* injected "Table of Contents" section is skipped.
+*/
+function extractSections(html, pageTitle, pageUrl) {
+	const source = html ?? "";
+	const records = [];
+	const headings = [];
+	HEADING_REGEX.lastIndex = 0;
+	let match = HEADING_REGEX.exec(source);
+	while (match !== null) {
+		headings.push({
+			level: Number.parseInt(match[1], 10),
+			anchor: match[2],
+			title: stripHtml(match[3]),
+			headingStart: match.index,
+			contentStart: match.index + match[0].length
+		});
+		match = HEADING_REGEX.exec(source);
+	}
+	const introEnd = headings.length > 0 ? headings[0].headingStart : source.length;
+	records.push({
+		id: pageUrl,
+		title: pageTitle,
+		titles: [],
+		text: stripHtml(source.slice(0, introEnd)),
+		url: pageUrl
+	});
+	const stack = [];
+	for (let index = 0; index < headings.length; index++) {
+		const heading = headings[index];
+		while (stack.length > 0 && stack[stack.length - 1].level >= heading.level) stack.pop();
+		if (isTableOfContents(heading.anchor, heading.title)) continue;
+		const next = headings[index + 1];
+		const sectionEnd = next ? next.headingStart : source.length;
+		const url = `${pageUrl}#${heading.anchor}`;
+		records.push({
+			id: url,
+			title: heading.title,
+			titles: [pageTitle, ...stack.map((item) => item.title)],
+			text: stripHtml(source.slice(heading.contentStart, sectionEnd)),
+			url
+		});
+		stack.push({
+			level: heading.level,
+			title: heading.title
+		});
+	}
+	return records;
+}
+/**
+* Build the full list of search records for a site from its documents and
+* (published) changelog entries.
+*/
+function generateSearchRecords(data) {
+	const records = [];
+	for (const document of data.documents ?? []) {
+		const pageTitle = document.navTitle || document.title || "Untitled";
+		const url = `${data.baseUrl}${stripIndexHtml(document.urlPath)}`;
+		records.push(...extractSections(document.generatedHtml, pageTitle, url));
+	}
+	for (const entry of data.changelogEntries ?? []) {
+		if (entry.draft) continue;
+		const pageTitle = entry.title || "Untitled";
+		const url = stripIndexHtml(entry.urlPath);
+		records.push(...extractSections(entry.generatedHtml, pageTitle, url));
+	}
+	return records;
+}
+/**
+* Generate the search index JSON for the build when search is enabled. The
+* file is written to the output root and consumed by the client-side search.
+*/
+async function buildSearchIndex(console, data) {
+	if (!data.enableSearch) return;
+	console.step("Building search index...");
+	await fs.promises.mkdir(data.output, { recursive: true });
+	const records = generateSearchRecords(data);
+	const outputPath = `${data.output}/${SEARCH_INDEX_FILENAME}`;
+	await fs.promises.writeFile(outputPath, JSON.stringify({ records }), "utf8");
+	console.fileBuilt(SEARCH_INDEX_FILENAME);
+}
+//#endregion
 //#region src/console.ts
 const ansiRegex = /\u001B\[[0-9;]*m/g;
 var DoculaConsole = class {
@@ -2513,6 +2962,11 @@ var DoculaOptions = class {
 	*/
 	enableLlmsTxt = true;
 	/**
+	* When true, generates a search index (search-index.json) and renders the
+	* search UI in templates that support it. Set to false to disable search.
+	*/
+	enableSearch = true;
+	/**
 	* Override the default theme toggle. By default the site follows the system
 	* preference. Set to "light" or "dark" to use that theme when no user
 	* preference is stored in localStorage.
@@ -2671,6 +3125,7 @@ var DoculaOptions = class {
 		if (options.enableReleaseChangelog !== void 0 && typeof options.enableReleaseChangelog === "boolean") this.enableReleaseChangelog = options.enableReleaseChangelog;
 		if (options.changelogPerPage !== void 0 && typeof options.changelogPerPage === "number" && options.changelogPerPage > 0) this.changelogPerPage = options.changelogPerPage;
 		if (options.enableLlmsTxt !== void 0 && typeof options.enableLlmsTxt === "boolean") this.enableLlmsTxt = options.enableLlmsTxt;
+		if (options.enableSearch !== void 0 && typeof options.enableSearch === "boolean") this.enableSearch = options.enableSearch;
 		if (options.themeMode !== void 0 && (options.themeMode === "light" || options.themeMode === "dark")) this.themeMode = options.themeMode;
 		if (options.autoUpdateIgnores !== void 0 && typeof options.autoUpdateIgnores === "boolean") this.autoUpdateIgnores = options.autoUpdateIgnores;
 		if (options.autoReadme !== void 0 && typeof options.autoReadme === "boolean") this.autoReadme = options.autoReadme;
@@ -2900,6 +3355,7 @@ var DoculaBuilder = class {
 		});
 		doculaData.changelogEntries = allChangelogEntries;
 		doculaData.hasChangelog = allChangelogEntries.length > 0 && hasChangelogTemplate;
+		doculaData.enableSearch = Boolean(this.options.enableSearch && (doculaData.hasDocuments || doculaData.hasChangelog));
 		/* v8 ignore next 40 -- @preserve */
 		if (this._options.ai) {
 			const aiModel = await createAIModel(this._options.ai);
@@ -3011,6 +3467,7 @@ var DoculaBuilder = class {
 		/* v8 ignore next 3 -- @preserve */
 		if (this.options.enableLlmsTxt) this._console.step("Building LLM files...");
 		await this.buildLlmsFiles(doculaData);
+		await this.buildSearchIndex(doculaData);
 		ensureCacheInGitignore(this._options, this._console, this.options.sitePath);
 		const newManifest = {
 			version: 1,
@@ -3041,6 +3498,7 @@ var DoculaBuilder = class {
 		const cwdReadmePath = path.join(cwdDir, "README.md");
 		if (!fs.existsSync(cwdReadmePath)) return;
 		let readmeContent = await fs.promises.readFile(cwdReadmePath, "utf8");
+		/* v8 ignore next -- split() always yields at least one element; ?? is defensive -- @preserve */
 		const firstLine = readmeContent.trimStart().split("\n")[0] ?? "";
 		if (!/^#\s+/.test(firstLine)) {
 			const packageJsonPath = path.join(cwdDir, "package.json");
@@ -3119,6 +3577,9 @@ var DoculaBuilder = class {
 	async buildLlmsFiles(data) {
 		return buildLlmsFiles(this._options, this._console, data);
 	}
+	async buildSearchIndex(data) {
+		return buildSearchIndex(this._console, data);
+	}
 	resolveOpenGraphData(data, pageUrl, pageData) {
 		return resolveOpenGraphData(data, pageUrl, pageData);
 	}
@@ -3360,14 +3821,14 @@ var Docula = class {
 			this._console.printHelp();
 			return;
 		}
-		if (consoleProcess.args.sitePath) this.options.sitePath = consoleProcess.args.sitePath;
-		await this.loadConfigFile(this.options.sitePath);
-		if (this._configFileModule.options) this.options.parseOptions(this._configFileModule.options);
-		if (this.options.quiet) this._console.quiet = true;
 		if (consoleProcess.command === "version") {
 			this._console.log(this.getVersion());
 			return;
 		}
+		if (consoleProcess.args.sitePath) this.options.sitePath = consoleProcess.args.sitePath;
+		await this.loadConfigFile(this.options.sitePath);
+		if (this._configFileModule.options) this.options.parseOptions(this._configFileModule.options);
+		if (this.options.quiet) this._console.quiet = true;
 		if (this._configFileModule.onPrepare) try {
 			await this._configFileModule.onPrepare(this.options, this._console);
 		} catch (error) {
@@ -3526,29 +3987,37 @@ var Docula = class {
 	*/
 	async loadConfigFile(sitePath) {
 		if (!fs.existsSync(sitePath)) return;
+		const jsonConfigFile = `${sitePath}/docula.config.json`;
 		const tsConfigFile = `${sitePath}/docula.config.ts`;
 		const mjsConfigFile = `${sitePath}/docula.config.mjs`;
+		/* v8 ignore start -- @preserve */
+		if (isSEA()) {
+			if (fs.existsSync(jsonConfigFile)) {
+				const content = fs.readFileSync(jsonConfigFile, "utf8");
+				this._configFileModule = { options: JSON.parse(content) };
+				return;
+			}
+			if (fs.existsSync(tsConfigFile) || fs.existsSync(mjsConfigFile)) throw new Error("Only docula.config.json is supported when running the standalone binary (Node.js SEA cannot dynamic-import file URLs). Convert your config to JSON, or run docula from Node.js to use .ts/.mjs configs.");
+			return;
+		}
+		/* v8 ignore stop */
 		/* v8 ignore next -- @preserve */
 		if (fs.existsSync(tsConfigFile)) {
 			const absolutePath = path.resolve(tsConfigFile);
-			const fileUrl = pathToFileURL(absolutePath).href;
-			if (isSEA()) try {
-				const mod = await import(fileUrl);
-				this._configFileModule = mod.default ?? mod;
-			} catch {
-				throw new Error("TypeScript config files require Node.js 22.6.0 or later when using the standalone binary. Please upgrade Node.js or use docula.config.mjs instead.");
-			}
-			else {
-				const { createJiti } = await import("jiti");
-				const jiti = createJiti(import.meta.url, { interopDefault: true });
-				this._configFileModule = await jiti.import(absolutePath);
-			}
+			const { createJiti } = await import("jiti");
+			const jiti = createJiti(import.meta.url, { interopDefault: true });
+			this._configFileModule = await jiti.import(absolutePath);
 			return;
 		}
 		/* v8 ignore next -- @preserve */
 		if (fs.existsSync(mjsConfigFile)) {
 			const absolutePath = path.resolve(mjsConfigFile);
 			this._configFileModule = await import(pathToFileURL(absolutePath).href);
+			return;
+		}
+		if (fs.existsSync(jsonConfigFile)) {
+			const content = fs.readFileSync(jsonConfigFile, "utf8");
+			this._configFileModule = { options: JSON.parse(content) };
 		}
 	}
 	/**