@waveso/docs 0.1.0

package/dist/render.js

@@ -0,0 +1,279 @@
+import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
+import { rehypeCaptureToc } from "./plugins/rehype-capture-toc.js";
+import { foldSegments, remarkDocLinks } from "./plugins/remark-doc-links.js";
+import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
+import { remarkYouTube } from "./plugins/remark-youtube.js";
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { rehypeGithubAlerts } from "rehype-github-alerts";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeSlug from "rehype-slug";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { CONTINUE, EXIT, visit } from "unist-util-visit";
+import { VFile } from "vfile";
+//#region src/render.ts
+/**
+* Markdown to hast, in Node, at build time.
+*
+* The output is a plain hast tree — serialisable JSON. It crosses the RSC
+* boundary, survives a `JSON.stringify` into any build-time artifact, and
+* caches to disk, all without the markdown parser or Shiki following it into
+* the browser. That is the product claim of this package, and stopping at hast
+* (rather than stringifying to HTML, or shipping MDX) is what buys it.
+*/
+/**
+* Emit a bare `<callout type="note">` instead of GitHub's markup.
+*
+* The default build ships octicon SVGs and `markdown-alert` classes, which
+* hardcodes an icon set and a stylesheet into the content tree. A single
+* element with a `type` is enough for the React layer to map onto a real
+* component that matches the rest of the site.
+*/
+const buildCallout = (alert, children) => ({
+	type: "element",
+	tagName: "callout",
+	properties: { type: alert.keyword.toLowerCase() },
+	children
+});
+/** The visible text of a heading permalink. Styling lives in the stylesheet. */
+const HEADING_ANCHOR_CONTENT = {
+	type: "text",
+	value: "#"
+};
+/**
+* Directory of a content-relative path, as segments.
+*
+* Split on both separators: the contract spells `relativePath` with forward
+* slashes, but a host that builds it from `path.relative` on Windows will not.
+*/
+function toDirSegments(relativePath) {
+	return relativePath.split(/[/\\]+/).slice(0, -1).filter(Boolean);
+}
+/** `scheme:` — `https:`, `data:`, anything that is not ours to resolve. */
+const IMAGE_HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/**
+* An image `src` folded against the page's directory, or `undefined` if it
+* climbs out of the content root.
+*
+* Absolute (`/logo.png`), protocol-relative and schemed sources are returned
+* UNCHANGED: they are already public URLs, and folding one would corrupt it.
+* Everything else is relative to the file that wrote it, which is what an
+* author means by `![](./diagram.png)` and what the link path has always done.
+*/
+function foldImageSrc(src, dirSegments) {
+	if (src.startsWith("/") || IMAGE_HAS_SCHEME.test(src)) return src;
+	const segments = foldSegments(dirSegments, src);
+	return segments === void 0 ? void 0 : segments.join("/");
+}
+/** Route without its `?query` / `#anchor`, for existence checks. */
+function toRouteKey(href) {
+	const cut = href.search(/[?#]/);
+	return cut === -1 ? href : href.slice(0, cut);
+}
+function describeLink(file, ref) {
+	const at = ref.line === void 0 ? "" : `:${ref.line}`;
+	return `${file.relativePath}${at}`;
+}
+/** Does the document already open on a page title? */
+function hasHeadingOne(tree) {
+	let found = false;
+	visit(tree, "element", (node) => {
+		if (node.tagName !== "h1") return CONTINUE;
+		found = true;
+		return EXIT;
+	});
+	return found;
+}
+/**
+* The `<h1>` a page gets when its markdown does not declare one.
+*
+* `DocFrontmatter.title` is documented as the `<h1>` fallback, and without it
+* a page whose body starts at `## ` ships with no `h1` at all: a broken
+* heading outline for anyone navigating by headings, and `page-has-heading-one`
+* for every accessibility audit. No id and no permalink — the page title is
+* addressable as the page.
+*/
+function titleHeadingNode(title) {
+	return {
+		type: "element",
+		tagName: "h1",
+		properties: {},
+		children: [{
+			type: "text",
+			value: title
+		}]
+	};
+}
+/**
+* Drop the `position` unist attaches to every node.
+*
+* The tree is the payload: it crosses the RSC boundary, so every byte is
+* shipped to every reader.
+* Positions are 38% of that JSON on a typical page — line and column offsets
+* into a markdown file the browser does not have and cannot fetch. Nothing
+* downstream reads them: link errors are reported from positions captured
+* during the mdast phase, and the TOC works off ids.
+*/
+function stripPositions(tree) {
+	visit(tree, (node) => {
+		delete node.position;
+	});
+	return tree;
+}
+/**
+* Build the processor once and reuse it for every file.
+*
+* The plugin order below is load-bearing and each step depends on the one
+* before it:
+*
+*  1. `remarkParse`         — markdown to mdast.
+*  2. `remarkGfm`           — tables, strikethrough, task lists, autolinks.
+*  3. `remarkDocLinks`      — rewrite links while paths are still mdast `url`
+*                             strings; after `remarkRehype` they are hast
+*                             properties and the source position is gone.
+*  4. `remarkUnwrapImages`  — must precede `remarkRehype` for the same reason:
+*                             the paragraph wrapper is created by the mdast to
+*                             hast conversion's phrasing rules.
+*  5. `remarkYouTube`       — after `remarkDocLinks`, which leaves an external
+*                             URL alone, and before `remarkRehype` on
+*                             `remarkUnwrapImages`'s reasoning: this replaces
+*                             the whole PARAGRAPH, because a block element left
+*                             inside the `<p>` markdown wraps a link in is
+*                             invalid HTML and hydrates as a mismatch.
+*  6. `remarkRehype`        — mdast to hast. `allowDangerousHtml` stays off:
+*                             raw HTML in the source is dropped rather than
+*                             passed through, because this package does not
+*                             run `rehype-raw`, and `rehype-raw` on its own
+*                             happily reparses `<script>` into the tree.
+*  7. `rehypeGithubAlerts`  — `> [!NOTE]` is still a blockquote at this point;
+*                             `remark-gfm` does not implement alerts at all.
+*                             Runs before slugging so a heading inside a
+*                             callout is slugged in its final position.
+*  8. `rehypeSlug`          — assigns heading ids.
+*  9. `rehypeCaptureToc`    — reads those ids. Before autolinking, so heading
+*                             text is captured without the appended `#`.
+* 10. `rehypeAutolinkHeadings` — appends the permalink.
+* 11. `rehypeShikiFromHighlighter` — last: it replaces `<pre><code>` wholesale,
+*                             and anything walking code blocks afterwards
+*                             would be walking Shiki's token spans instead.
+*/
+async function buildProcessor(options) {
+	const themes = options.themes ?? DEFAULT_DOCS_THEMES;
+	const highlighter = await (options.highlighter ?? createDocsHighlighter({
+		themes,
+		...options.langs === void 0 ? {} : { langs: options.langs }
+	}));
+	return unified().use(remarkParse).use(remarkGfm).use(remarkDocLinks, {
+		basePath: options.config.basePath,
+		...options.linkResolver === void 0 ? {} : { resolve: options.linkResolver }
+	}).use(remarkUnwrapImages).use(remarkYouTube).use(remarkRehype, {
+		allowDangerousHtml: false,
+		footnoteLabelProperties: { className: ["wave-docs-sr-only"] }
+	}).use(rehypeGithubAlerts, { build: buildCallout }).use(rehypeSlug).use(rehypeCaptureToc).use(rehypeAutolinkHeadings, {
+		behavior: "append",
+		content: HEADING_ANCHOR_CONTENT,
+		properties: {
+			className: ["heading-anchor"],
+			ariaHidden: "true",
+			tabIndex: -1
+		}
+	}).use(rehypeShikiFromHighlighter, highlighter, {
+		themes,
+		fallbackLanguage: "text",
+		defaultLanguage: "text"
+	}).freeze();
+}
+/**
+* Create a renderer.
+*
+* The processor and the highlighter are built once, eagerly, and shared by
+* every call to `render`. Constructing them per file is the difference between
+* a docs build that takes a second and one that takes a minute.
+*/
+function createDocsRenderer(options) {
+	const processorPromise = buildProcessor(options);
+	const { config, imageResolver, knownRoutes } = options;
+	const titleHeading = options.titleHeading ?? true;
+	/**
+	* Hand every `<img>` to the resolver, FOLDED AND CONTAINED.
+	*
+	* ⚠️ IMAGES USED TO SKIP FOLDING ENTIRELY. `remarkDocLinks` visits `link` and
+	* `definition` and never `image`, so an image `src` reached the resolver
+	* exactly as authored — `../../../../.env` included — while every LINK on the
+	* same page went through `foldSegments`, which refuses a chain that climbs
+	* out of the content root. Two paths into the same kind of consumer code,
+	* one of them guarded.
+	*
+	* That is a containment hole rather than a formatting bug: the resolver's
+	* documented job is to turn a src into a public URL, and a reasonable
+	* implementation joins it onto a directory. So the fold happens HERE, before
+	* the call, and an escape throws with the file named — the same treatment
+	* `assertLinks` gives a link that climbs out.
+	*
+	* Absolute and external srcs are passed through untouched: `/logo.png` is
+	* already a public URL and `https://…` belongs to someone else.
+	*/
+	async function resolveImages(tree, file, resolve) {
+		const images = [];
+		visit(tree, "element", (node) => {
+			if (node.tagName === "img") images.push(node);
+		});
+		const context = {
+			segments: file.segments,
+			dirSegments: toDirSegments(file.relativePath),
+			relativePath: file.relativePath
+		};
+		await Promise.all(images.map(async (node) => {
+			const src = node.properties.src;
+			if (typeof src !== "string" || src === "") return;
+			const folded = foldImageSrc(src, context.dirSegments);
+			if (folded === void 0) throw new Error(`@waveso/docs: image "${src}" in ${file.relativePath} climbs above the content root.`);
+			const resolved = await resolve(folded, context);
+			if (resolved === void 0) return;
+			node.properties.src = resolved.src;
+			if (resolved.width !== void 0) node.properties.width = resolved.width;
+			if (resolved.height !== void 0) node.properties.height = resolved.height;
+		}));
+	}
+	/**
+	* Fail the build on a link that would have 404'd.
+	*
+	* Deliberately a throw and not a warning: the link was valid in the editor
+	* and on GitHub, so a warning in a build log is a warning nobody reads.
+	*/
+	function assertLinks(file, refs) {
+		for (const ref of refs) {
+			if (ref.href === void 0) throw new Error(`@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
+			if (knownRoutes === void 0) continue;
+			const route = toRouteKey(ref.href);
+			if (!knownRoutes.has(route)) throw new Error(`@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists. Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
+		}
+	}
+	return { async render(file) {
+		const processor = await processorPromise;
+		const vfile = new VFile({
+			value: file.content,
+			path: file.filePath
+		});
+		vfile.data.docLinkContext = {
+			segments: file.segments,
+			dirSegments: toDirSegments(file.relativePath),
+			relativePath: file.relativePath
+		};
+		const hast = await processor.run(processor.parse(vfile), vfile);
+		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
+		if (imageResolver !== void 0) await resolveImages(hast, file, imageResolver);
+		if (config.assertLinks) assertLinks(file, vfile.data.docLinks ?? []);
+		return {
+			frontmatter: file.frontmatter,
+			hast: stripPositions(hast),
+			toc: vfile.data.toc ?? [],
+			segments: file.segments,
+			href: file.href
+		};
+	} };
+}
+//#endregion
+export { createDocsRenderer };

package/dist/search-index.d.ts

@@ -0,0 +1,51 @@
+import { RenderedDoc, SearchRecord } from "./types.js";
+//#region src/search-index.d.ts
+/** Options for {@link extractSearchRecords}. */
+interface ExtractSearchRecordsOptions {
+  /**
+   * Maximum length of {@link SearchRecord.text}, in characters. Defaults to
+   * 300 — long enough to carry a section's vocabulary into the index, short
+   * enough that a 300-page corpus stays under a megabyte.
+   */
+  excerptLength?: number;
+}
+/**
+ * Split a rendered document into section-scoped {@link SearchRecord}s.
+ *
+ * One record per `h2`–`h6`, plus a lead record covering everything before the
+ * first heading. The lead record is always emitted: it is what makes a page
+ * findable by its title even when every section under it is empty.
+ *
+ * Anchors are read from the ids `rehype-slug` already put on the tree. They
+ * are never recomputed — a second slugger seeded independently drifts exactly
+ * where it hurts, on duplicate headings that carry `-1` collision suffixes.
+ *
+ * A heading with no usable id opens no section: `github-slugger` returns the
+ * empty string for `## 🚀`, and there is nothing to deep-link to. Its text is
+ * folded into the enclosing section instead, which is what `rehypeCaptureToc`
+ * does with the same heading — the two must not disagree about which sections
+ * exist.
+ *
+ * Not generic over the frontmatter type, deliberately: `frontmatter.title` is
+ * the only field read, and a `RenderedDoc` carrying a project's own fields is
+ * assignable to this signature already. A type parameter here would appear in
+ * every call site and constrain nothing.
+ */
+declare function extractSearchRecords(doc: RenderedDoc, options?: ExtractSearchRecordsOptions): SearchRecord[];
+/**
+ * Build a serialised MiniSearch index from extracted records.
+ *
+ * The return value is JSON, ready for `MiniSearch.loadJSON` on the client or
+ * for {@link writeSearchIndex} to put on disk.
+ */
+declare function buildSearchIndex(records: SearchRecord[]): string;
+/**
+ * Write the serialised index to `outFile`, creating parent directories.
+ *
+ * Returns the byte size written, so a build step can log it or assert a
+ * budget — a docs index that quietly crosses a megabyte is a regression
+ * nobody notices until the dialog takes a second to open.
+ */
+declare function writeSearchIndex(records: SearchRecord[], outFile: string): Promise<number>;
+//#endregion
+export { ExtractSearchRecordsOptions, buildSearchIndex, extractSearchRecords, writeSearchIndex };

package/dist/search-index.js

@@ -0,0 +1,274 @@
+import { SEARCH_INDEX_OPTIONS } from "./search-options.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import MiniSearch from "minisearch";
+//#region src/search-index.ts
+/**
+* Build-time search index construction.
+*
+* Node-only, and deliberately so: the markdown parser, the hast walk and
+* MiniSearch's index builder all run once per build, and the browser receives
+* nothing but the serialised result. `src/react/search-dialog.tsx` is the
+* matching client half.
+*
+* MiniSearch over Fuse.js is a measured choice, not a taste one: on a 282-page
+* corpus Fuse ran 96.6 ms median / 298 ms max per query against MiniSearch's
+* 1.35 ms / 3.84 ms. Fuse is a fuzzy short-string matcher routinely
+* misapplied to full text.
+*/
+/** Default excerpt length, in characters, of {@link SearchRecord.text}. */
+const DEFAULT_EXCERPT_LENGTH = 300;
+/** `<h1>`…`<h6>` to their numeric depth. */
+const HEADING_DEPTHS = /* @__PURE__ */ new Map([
+	["h1", 1],
+	["h2", 2],
+	["h3", 3],
+	["h4", 4],
+	["h5", 5],
+	["h6", 6]
+]);
+/**
+* Elements whose text never belongs in the index.
+*
+* `pre` is the important one: after Shiki, a code block is hundreds of
+* `<span class="line">` token wrappers whose text indexes as a bag of
+* punctuation and keyword fragments. It inflates the index and poisons
+* relevance. Inline `code` is kept — `useMemo` is exactly the sort of thing
+* people search for.
+*/
+const SKIPPED_TAGS = /* @__PURE__ */ new Set([
+	"pre",
+	"script",
+	"style",
+	"svg",
+	"template"
+]);
+/**
+* Containers that merely wrap content rather than nesting it semantically.
+*
+* Walking through them keeps heading detection working when a rehype plugin
+* (or a consumer's own) wraps the document body, without descending into
+* blockquotes or list items where a heading is not a section boundary.
+*/
+const TRANSPARENT_TAGS = /* @__PURE__ */ new Set([
+	"div",
+	"section",
+	"article",
+	"main"
+]);
+/**
+* The GFM footnote block `mdast-util-to-hast` appends, and everything in it.
+*
+* It is a `section` — so {@link TRANSPARENT_TAGS} would otherwise walk straight
+* into it — carrying a generated `<h2 id="footnote-label">Footnotes</h2>`. That
+* heading is machinery, not a section of the page: indexing it puts a
+* `Footnotes` hit in the dialog for every footnoted page, and the footnote text
+* itself is already indexed where it was written. `rehypeCaptureToc` skips the
+* same subtree, so the TOC and the index agree.
+*/
+function isFootnotes(node) {
+	return node.properties.dataFootnotes !== void 0;
+}
+/** Tags after which extracted text needs a separator. */
+const BLOCK_TAGS = /* @__PURE__ */ new Set([
+	"address",
+	"blockquote",
+	"br",
+	"dd",
+	"details",
+	"div",
+	"dl",
+	"dt",
+	"figcaption",
+	"figure",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"hr",
+	"li",
+	"ol",
+	"p",
+	"section",
+	"summary",
+	"table",
+	"tbody",
+	"td",
+	"th",
+	"thead",
+	"tr",
+	"ul"
+]);
+/**
+* Split a rendered document into section-scoped {@link SearchRecord}s.
+*
+* One record per `h2`–`h6`, plus a lead record covering everything before the
+* first heading. The lead record is always emitted: it is what makes a page
+* findable by its title even when every section under it is empty.
+*
+* Anchors are read from the ids `rehype-slug` already put on the tree. They
+* are never recomputed — a second slugger seeded independently drifts exactly
+* where it hurts, on duplicate headings that carry `-1` collision suffixes.
+*
+* A heading with no usable id opens no section: `github-slugger` returns the
+* empty string for `## 🚀`, and there is nothing to deep-link to. Its text is
+* folded into the enclosing section instead, which is what `rehypeCaptureToc`
+* does with the same heading — the two must not disagree about which sections
+* exist.
+*
+* Not generic over the frontmatter type, deliberately: `frontmatter.title` is
+* the only field read, and a `RenderedDoc` carrying a project's own fields is
+* assignable to this signature already. A type parameter here would appear in
+* every call site and constrain nothing.
+*/
+function extractSearchRecords(doc, options = {}) {
+	const excerptLength = options.excerptLength ?? DEFAULT_EXCERPT_LENGTH;
+	const title = doc.frontmatter.title;
+	const records = [];
+	const slug = doc.segments.join("/");
+	/** Open headings, outermost first, that enclose the current section. */
+	const ancestors = [];
+	let section = {
+		heading: title,
+		anchor: void 0,
+		ancestors: [],
+		parts: []
+	};
+	const flush = () => {
+		const href = section.anchor === void 0 ? doc.href : `${doc.href}#${section.anchor}`;
+		const id = section.anchor === void 0 ? slug : `${slug}#${section.anchor}`;
+		records.push({
+			id,
+			title,
+			heading: section.heading,
+			ancestors: section.ancestors,
+			href,
+			text: truncateAtWordBoundary(collapseWhitespace(section.parts.join(" ")), excerptLength)
+		});
+	};
+	for (const node of iterateBlocks(doc.hast.children)) {
+		if (node.type === "element") {
+			const depth = HEADING_DEPTHS.get(node.tagName);
+			if (depth === 1) continue;
+			if (depth !== void 0) {
+				const anchor = readHeadingId(node);
+				const heading = extractHeadingText(node);
+				if (anchor === void 0) {
+					if (heading !== "") section.parts.push(heading);
+					continue;
+				}
+				flush();
+				while (ancestors.length > 0) {
+					const open = ancestors[ancestors.length - 1];
+					if (open === void 0 || open.depth < depth) break;
+					ancestors.pop();
+				}
+				section = {
+					heading,
+					anchor,
+					ancestors: ancestors.map((ancestor) => ancestor.text),
+					parts: []
+				};
+				ancestors.push({
+					depth,
+					text: heading
+				});
+				continue;
+			}
+		}
+		const text = collapseWhitespace(extractText(node));
+		if (text !== "") section.parts.push(text);
+	}
+	flush();
+	return records;
+}
+/**
+* Yield block-level nodes in document order, stepping through wrapper
+* elements so a heading inside one still reads as a section boundary.
+*/
+function* iterateBlocks(nodes) {
+	for (const node of nodes) {
+		if (node.type === "element" && isFootnotes(node)) continue;
+		if (node.type === "element" && TRANSPARENT_TAGS.has(node.tagName)) yield* iterateBlocks(node.children);
+		else yield node;
+	}
+}
+/** Plain text of a node, minus code blocks and presentational cruft. */
+function extractText(node) {
+	const parts = [];
+	collectText(node, parts);
+	return parts.join("");
+}
+function collectText(node, out) {
+	if (node.type === "text") {
+		out.push(node.value);
+		return;
+	}
+	if (node.type !== "element") return;
+	if (SKIPPED_TAGS.has(node.tagName) || isPresentational(node)) return;
+	for (const child of node.children) collectText(child, out);
+	if (BLOCK_TAGS.has(node.tagName)) out.push(" ");
+}
+/**
+* `aria-hidden` / `hidden` elements are decoration — the anchor icon
+* `rehype-autolink-headings` appends, the alert icons `rehype-github-alerts`
+* injects — and none of it is text a reader would search for.
+*/
+function isPresentational(node) {
+	const properties = node.properties;
+	if (properties === void 0) return false;
+	const ariaHidden = properties.ariaHidden;
+	const hidden = properties.hidden;
+	return ariaHidden === true || ariaHidden === "true" || hidden === true;
+}
+function extractHeadingText(node) {
+	return collapseWhitespace(extractText(node)).replace(/\s+#+$/, "");
+}
+/** The heading's anchor, or `undefined` when nothing can link to it. */
+function readHeadingId(node) {
+	const id = node.properties?.id;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function collapseWhitespace(text) {
+	return text.replace(/\s+/g, " ").trim();
+}
+/**
+* Cut `text` to at most `limit` characters, on a word boundary where one is
+* near enough to the cut to be worth honouring.
+*/
+function truncateAtWordBoundary(text, limit) {
+	if (limit <= 0) return "";
+	if (text.length <= limit) return text;
+	const slice = text.slice(0, limit);
+	const lastSpace = slice.lastIndexOf(" ");
+	return `${(lastSpace > limit / 2 ? slice.slice(0, lastSpace) : slice).trimEnd()}…`;
+}
+/**
+* Build a serialised MiniSearch index from extracted records.
+*
+* The return value is JSON, ready for `MiniSearch.loadJSON` on the client or
+* for {@link writeSearchIndex} to put on disk.
+*/
+function buildSearchIndex(records) {
+	const index = new MiniSearch(SEARCH_INDEX_OPTIONS);
+	index.addAll(records);
+	return JSON.stringify(index);
+}
+/**
+* Write the serialised index to `outFile`, creating parent directories.
+*
+* Returns the byte size written, so a build step can log it or assert a
+* budget — a docs index that quietly crosses a megabyte is a regression
+* nobody notices until the dialog takes a second to open.
+*/
+async function writeSearchIndex(records, outFile) {
+	const json = buildSearchIndex(records);
+	const absolute = path.resolve(outFile);
+	await mkdir(path.dirname(absolute), { recursive: true });
+	await writeFile(absolute, json, "utf8");
+	return Buffer.byteLength(json, "utf8");
+}
+//#endregion
+export { buildSearchIndex, extractSearchRecords, writeSearchIndex };

package/dist/search-options.d.ts

@@ -0,0 +1,18 @@
+import { SearchRecord } from "./types.js";
+import { Options } from "minisearch";
+//#region src/search-options.d.ts
+/**
+ * Fields, stored fields and query defaults for the docs index.
+ *
+ * `storeFields` MUST be applied at build time. It decides what
+ * `MiniSearch.toJSON()` carries; passing it to `loadJSON` on the client cannot
+ * recover fields the serialised index never stored, and the failure is silent
+ * — results arrive with an id and a score and nothing to render.
+ *
+ * `combineWith: 'AND'` is not MiniSearch's default and is not optional here.
+ * The default OR returned 68–131 hits on real queries where AND returned a
+ * usable handful.
+ */
+declare const SEARCH_INDEX_OPTIONS: Options<SearchRecord>;
+//#endregion
+export { SEARCH_INDEX_OPTIONS };

package/dist/search-options.js

@@ -0,0 +1,40 @@
+//#region src/search-options.ts
+/**
+* Fields, stored fields and query defaults for the docs index.
+*
+* `storeFields` MUST be applied at build time. It decides what
+* `MiniSearch.toJSON()` carries; passing it to `loadJSON` on the client cannot
+* recover fields the serialised index never stored, and the failure is silent
+* — results arrive with an id and a score and nothing to render.
+*
+* `combineWith: 'AND'` is not MiniSearch's default and is not optional here.
+* The default OR returned 68–131 hits on real queries where AND returned a
+* usable handful.
+*/
+const SEARCH_INDEX_OPTIONS = {
+	fields: [
+		"title",
+		"heading",
+		"text",
+		"ancestors"
+	],
+	storeFields: [
+		"title",
+		"heading",
+		"ancestors",
+		"href"
+	],
+	searchOptions: {
+		prefix: true,
+		fuzzy: .2,
+		combineWith: "AND",
+		boost: {
+			title: 4,
+			heading: 3,
+			text: 2,
+			ancestors: 1
+		}
+	}
+};
+//#endregion
+export { SEARCH_INDEX_OPTIONS };