@waveso/docs 0.3.0 → 0.5.0

package/dist/search-options.d.ts

@@ -1,5 +1,5 @@
 import { SearchRecord } from "./types.js";
-import { Options } from "minisearch";
+import { Options, SearchOptions } from "minisearch";
 //#region src/search-options.d.ts
 /**
  * Split text into index terms.
@@ -45,5 +45,67 @@ declare const SEARCH_INDEX_OPTIONS: Options<SearchRecord>;
  * OR. Nothing below that merges: a `boost` override replaces the whole map.
  */
 declare function mergeSearchOptions(overrides?: Partial<Options<SearchRecord>>): Options<SearchRecord>;
+/**
+ * {@link SearchOptions} with every function-valued member removed.
+ *
+ * `prefix` and `fuzzy` survive as the boolean and the number they usually are;
+ * their function overloads do not, because a predicate cannot be serialised.
+ */
+type SerializableSearchQueryOptions = Omit<SearchOptions, 'filter' | 'boostTerm' | 'boostDocument' | 'tokenize' | 'processTerm' | 'prefix' | 'fuzzy'> & {
+  prefix?: boolean;
+  fuzzy?: boolean | number;
+};
+/**
+ * MiniSearch overrides that can be handed from a Server Component to a Client
+ * Component — which is to say, the ones with no functions in them.
+ *
+ * React serialises a Client Component's props, and a function is not
+ * serialisable: `docs.Layout` forwarding `{ processTerm }` into `DocsSearch`
+ * fails `next build` outright with *"Functions cannot be passed directly to
+ * Client Components"*. This type is what stops that being expressible.
+ *
+ * ⚠️ THE OMIT LIST IS NOT THE GUARANTEE — {@link findFunctionValuedOptions} IS.
+ * MiniSearch is free to add a function-valued option in a minor, and the day it
+ * does this list is quietly incomplete while still compiling. The runtime walk
+ * has no such failure mode: it finds a function wherever it is, including in
+ * options this package has never heard of. The type is here to fail earlier and
+ * more legibly, not to be the last line of defence.
+ *
+ * The escape hatch for real function tuning is a client boundary of the host's
+ * own, which is the only place the two halves can share a module reference:
+ *
+ * ```tsx
+ * // app/docs/search.tsx
+ * 'use client';
+ * import { DocsSearch } from '@waveso/docs/react/next-search';
+ * import { processTerm } from '@/lib/search-terms';
+ *
+ * export function Search({ indexUrl }: { indexUrl: string }) {
+ *   return <DocsSearch indexUrl={indexUrl} miniSearchOptions={{ processTerm }} />;
+ * }
+ * ```
+ *
+ * That component takes the boundary with it, so the function is a module import
+ * on both sides rather than a prop crossing between them — exactly how
+ * {@link tokenizeSearchText} reaches the client today.
+ */
+type SerializableSearchOptions = Omit<Partial<Options<SearchRecord>>, 'extractField' | 'stringifyField' | 'tokenize' | 'processTerm' | 'logger' | 'searchOptions' | 'autoSuggestOptions'> & {
+  searchOptions?: SerializableSearchQueryOptions;
+  autoSuggestOptions?: SerializableSearchQueryOptions;
+};
+/**
+ * Dotted paths of every function reachable from `options`, in encounter order.
+ *
+ * The load-bearing half of the boundary check, and deliberately structural
+ * rather than a key list: it answers for `processTerm`, for
+ * `searchOptions.filter`, and for whatever MiniSearch adds next, because it
+ * asks what the values *are* rather than what they are called.
+ *
+ * `seen` makes a cyclic options object an empty answer rather than a stack
+ * overflow. Nothing in MiniSearch's surface is cyclic, but a hang during
+ * `next build` is a far worse failure than a wrong one, and the guard is a
+ * line.
+ */
+declare function findFunctionValuedOptions(options: object, prefix?: string, seen?: WeakSet<object>): string[];
 //#endregion
-export { SEARCH_INDEX_OPTIONS, mergeSearchOptions, tokenizeSearchText };
+export { SEARCH_INDEX_OPTIONS, SerializableSearchOptions, SerializableSearchQueryOptions, findFunctionValuedOptions, mergeSearchOptions, tokenizeSearchText };

package/dist/search-options.js

@@ -99,5 +99,29 @@ function mergeSearchOptions(overrides = {}) {
 		}
 	};
 }
+/**
+* Dotted paths of every function reachable from `options`, in encounter order.
+*
+* The load-bearing half of the boundary check, and deliberately structural
+* rather than a key list: it answers for `processTerm`, for
+* `searchOptions.filter`, and for whatever MiniSearch adds next, because it
+* asks what the values *are* rather than what they are called.
+*
+* `seen` makes a cyclic options object an empty answer rather than a stack
+* overflow. Nothing in MiniSearch's surface is cyclic, but a hang during
+* `next build` is a far worse failure than a wrong one, and the guard is a
+* line.
+*/
+function findFunctionValuedOptions(options, prefix = "", seen = /* @__PURE__ */ new WeakSet()) {
+	if (seen.has(options)) return [];
+	seen.add(options);
+	const found = [];
+	for (const [key, value] of Object.entries(options)) {
+		const path = prefix === "" ? key : `${prefix}.${key}`;
+		if (typeof value === "function") found.push(path);
+		else if (typeof value === "object" && value !== null) found.push(...findFunctionValuedOptions(value, path, seen));
+	}
+	return found;
+}
 //#endregion
-export { SEARCH_INDEX_OPTIONS, mergeSearchOptions, tokenizeSearchText };
+export { SEARCH_INDEX_OPTIONS, findFunctionValuedOptions, mergeSearchOptions, tokenizeSearchText };

package/dist/semaphore.d.ts

@@ -0,0 +1,46 @@
+//#region src/semaphore.d.ts
+/**
+ * A counting semaphore, for bounding how much of a process resource is in use.
+ *
+ * Private — deliberately not an entry point in `package.json`.
+ *
+ * {@link mapPooled} bounds a fan-out over a list, which is the easy case: the
+ * list is known, so the pool can pull from it. A recursive tree walk has no
+ * list — `scanDir` calls itself once per subdirectory, so a per-call pool
+ * bounds each directory and multiplies across the depth, which is not a bound
+ * at all. That is what this is for.
+ *
+ * ⚠️ NEVER ACQUIRE A SLOT WHILE HOLDING ONE. Nested acquisition deadlocks the
+ * moment every slot is held by a caller waiting for a slot, and no amount of
+ * timeout rescues it. Guard the leaf operation — the `readFile`, the `readdir`
+ * — and never the recursive call around it. In `source.ts` this is why the
+ * traversal itself is ungated: only the filesystem calls take slots, so the
+ * descriptors are bounded exactly while the walk stays as parallel as it was.
+ */
+/** @see createSemaphore */
+interface Semaphore {
+  /**
+   * Run `fn` once a slot is free, and give the slot back when it settles.
+   *
+   * Rejections propagate untouched, and release the slot on the way out.
+   */
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A semaphore admitting `limit` concurrent callers.
+ *
+ * Waiters are woken in arrival order, so a long queue cannot starve its head.
+ *
+ * A limit below one falls back to one, for the same reason {@link mapPooled}
+ * clamps: a caller passing `0` — or a negative, from arithmetic on a config
+ * value — would otherwise admit nobody, and the symptom is a build that hangs
+ * rather than one that fails.
+ *
+ * ⚠️ `Math.max(1, limit)` IS NOT ENOUGH, BECAUSE `Math.max(1, NaN)` IS `NaN`.
+ * With `max` set to `NaN`, `active >= max` is false forever and the semaphore
+ * admits everyone — no hang, no error, and no bound, which is the one outcome
+ * worse than either. Non-finite means one.
+ */
+declare function createSemaphore(limit: number): Semaphore;
+//#endregion
+export { Semaphore, createSemaphore };

package/dist/semaphore.js

@@ -0,0 +1,60 @@
+//#region src/semaphore.ts
+/**
+* A semaphore admitting `limit` concurrent callers.
+*
+* Waiters are woken in arrival order, so a long queue cannot starve its head.
+*
+* A limit below one falls back to one, for the same reason {@link mapPooled}
+* clamps: a caller passing `0` — or a negative, from arithmetic on a config
+* value — would otherwise admit nobody, and the symptom is a build that hangs
+* rather than one that fails.
+*
+* ⚠️ `Math.max(1, limit)` IS NOT ENOUGH, BECAUSE `Math.max(1, NaN)` IS `NaN`.
+* With `max` set to `NaN`, `active >= max` is false forever and the semaphore
+* admits everyone — no hang, no error, and no bound, which is the one outcome
+* worse than either. Non-finite means one.
+*/
+function createSemaphore(limit) {
+	const requested = Math.floor(limit);
+	const max = Number.isFinite(requested) && requested >= 1 ? requested : 1;
+	const waiting = [];
+	let active = 0;
+	/**
+	* Hand the slot to the next waiter rather than releasing and re-taking it.
+	*
+	* The naive form — decrement here, let the woken waiter increment itself — is
+	* *equivalent*, and this was written that way first on the assumption that it
+	* was not. It is equivalent because the decrement and the wake happen in one
+	* synchronous step: no microtask can be interposed between them, and anything
+	* enqueued earlier runs before this function rather than inside it, so there
+	* is no window for a caller to read `active` below the limit. Mutation-tested
+	* — swapping in the naive form fails nothing, which is the honest result.
+	*
+	* It stays this way because that argument is about the scheduler rather than
+	* about this code. One `await` between the decrement and the wake and the
+	* bound is gone, with nothing able to observe it. Handing the slot over makes
+	* `active` a count of owned slots at every point, whoever holds them, so the
+	* invariant is local and needs no argument at all.
+	*/
+	const release = () => {
+		const next = waiting.shift();
+		if (next !== void 0) {
+			next();
+			return;
+		}
+		active -= 1;
+	};
+	return { async run(fn) {
+		if (active >= max) await new Promise((resolve) => {
+			waiting.push(resolve);
+		});
+		else active += 1;
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	} };
+}
+//#endregion
+export { createSemaphore };

package/dist/source.js

@@ -1,6 +1,7 @@
 import { docsError } from "./docs-error.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { orderNavEntries, readDocsMeta } from "./meta.js";
+import { createSemaphore } from "./semaphore.js";
 import { encodeSegments, toAliasRoute } from "./route-path.js";
 import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
@@ -12,6 +13,48 @@ const PAGE_EXTENSION = ".md";
 /** A directory whose `index.md` is the directory's own route. */
 const INDEX_NAME = "index";
 /**
+* Filesystem calls in flight across the whole process, at most.
+*
+* ⚠️ THE SCAN USED TO OPEN EVERY MARKDOWN FILE AT ONCE. `scanDir` recursed into
+* its subdirectories in parallel and read that directory's pages with a bare
+* `Promise.all`, so the number of `readFile` calls in flight equalled the number
+* of markdown files in the entire tree. On a 1,200-page corpus and the common
+* 1,024-descriptor soft limit, `next build` died with a bare `EMFILE: too many
+* open files` — no error code, no mention that this was the docs scan, and
+* nothing pointing at the fix. Exactly the large content set this package is
+* for, and the failure got worse as the site grew.
+*
+* 64 is far under every default soft limit — 1,024 on Linux and CI images, 256
+* on an unconfigured macOS shell — so the descriptors stop scaling with the
+* corpus while staying safe on the tightest of those.
+*
+* ⚠️ IT IS NOT FREE, AND THE COST IS NOT THE CONCURRENCY. Measured over 1,201
+* pages in 49 directories, nine runs, medians: **88 ms ungated, 106 ms at a
+* bound of 16, 102 ms at 64, 101 ms at 128 and at 256.** Flat from 64 upwards,
+* which says the ~14 ms is the gate's own per-call overhead — about 3,600
+* `run` closures — and not the reduced parallelism. libuv's filesystem pool is
+* four threads by default, so there was never 1,201-way parallelism to lose.
+*
+* So the number is chosen for the tightest descriptor limit rather than for
+* speed, because above 64 there is no speed left to buy. 14 ms sits against a
+* build that highlights those same 1,201 pages with Shiki, which is three
+* orders of magnitude more.
+*/
+const SCAN_CONCURRENCY = 64;
+/**
+* The one gate, for the whole process.
+*
+* Module scope rather than per-scan, because descriptors are a process resource:
+* two routes scanning two content directories at once would each stay under a
+* per-scan bound and together exceed the only one that matters.
+*
+* ⚠️ LEAF CALLS ONLY — NEVER THE RECURSION. Gating `scanDir` itself deadlocks as
+* soon as every slot is held by a directory waiting for a slot to read its
+* children. Bounding the `readFile`/`readdir`/`stat`/`realpath` calls bounds the
+* descriptors exactly, and leaves the walk as parallel as it was.
+*/
+const fsGate = createSemaphore(SCAN_CONCURRENCY);
+/**
 * Apply {@link DocsConfig} defaults and resolve `contentDir` against
 * `process.cwd()` — the project root under both `next build` and `vite build`.
 *
@@ -85,7 +128,7 @@ function buildSource(config) {
 	const load = () => {
 		cached ??= scan(config).catch((err) => {
 			cached = null;
-			throw err;
+			throw describeScanFailure(err, config.contentDir);
 		});
 		return cached;
 	};
@@ -143,9 +186,32 @@ function buildSource(config) {
 		}
 	};
 }
+/**
+* Say that a descriptor exhaustion happened here, and that it was not us.
+*
+* `EMFILE`/`ENFILE` arrive from Node as a bare `Error` with no hint of what was
+* being read, and the message a reader used to get was
+* `EMFILE: too many open files, open '<contentDir>/p829.md'` and nothing else.
+* That is a filename out of a corpus of a thousand, from a stack of `dist/`
+* frames, during a `next build` that mentions no package.
+*
+* The scan itself is bounded at {@link SCAN_CONCURRENCY} now, so reaching this
+* means the limit is lower than that or something else in the process has the
+* descriptors — which is the useful thing to be told, and the opposite of what a
+* reader concludes from an error naming one of their own markdown files.
+*
+* Only these two codes, and only when the failure is not already ours: a
+* `broken-symlink` or an `invalid-frontmatter` that came out of the scan is
+* already a better message than anything this could add.
+*/
+function describeScanFailure(err, contentDir) {
+	const code = err?.code;
+	if (code !== "EMFILE" && code !== "ENFILE") return err;
+	return docsError("descriptor-limit", `the process ran out of file descriptors while scanning ${contentDir}. The scan holds at most ${String(SCAN_CONCURRENCY)} open at a time, so something else has them — raise the limit (\`ulimit -n\`, or \`LimitNOFILE\` under systemd) rather than shrinking the corpus. If it persists with a limit well above that, it is a bug in this package: https://github.com/wavedotso/wave-docs/issues`, { cause: err });
+}
 async function scan(config) {
 	await assertContentDir(config.contentDir);
-	const root = await scanDir(config.contentDir, [], "", config, /* @__PURE__ */ new Set([await realpath(config.contentDir)]));
+	const root = await scanDir(config.contentDir, [], "", config, /* @__PURE__ */ new Set([await fsGate.run(() => realpath(config.contentDir))]));
 	const files = [];
 	const bySlug = /* @__PURE__ */ new Map();
 	collect(root, files, bySlug);
@@ -157,13 +223,13 @@ async function scan(config) {
 }
 async function assertContentDir(contentDir) {
 	try {
-		if ((await stat(contentDir)).isDirectory()) return;
+		if ((await fsGate.run(() => stat(contentDir))).isDirectory()) return;
 	} catch {}
 	throw docsError("missing-content-dir", `Docs content directory not found: ${contentDir}\nSet \`contentDir\` to a directory of markdown files; relative paths resolve against the working directory (${process.cwd()}).`);
 }
 const SKIP = { kind: "skip" };
 async function scanDir(absPath, segments, name, config, ancestors) {
-	const [meta, entries] = await Promise.all([readDocsMeta(absPath), readdir(absPath, { withFileTypes: true })]);
+	const [meta, entries] = await Promise.all([fsGate.run(() => readDocsMeta(absPath)), fsGate.run(() => readdir(absPath, { withFileTypes: true }))]);
 	const classified = await Promise.all(entries.map((entry) => ({
 		entry,
 		name: entry.name.normalize("NFC")
@@ -206,7 +272,7 @@ async function classifyEntry(dirPath, entry, name) {
 		if (!entry.isSymbolicLink()) return SKIP;
 		let target;
 		try {
-			target = await stat(absPath);
+			target = await fsGate.run(() => stat(absPath));
 		} catch {
 			if (!isPageFile(name)) return SKIP;
 			throw docsError("broken-symlink", `@waveso/docs: ${absPath} is a broken symbolic link, and it names a markdown page — so skipping it would delete a route nobody asked to delete. Point it at an existing file, or remove the link.`);
@@ -223,20 +289,23 @@ async function classifyEntry(dirPath, entry, name) {
 		kind: "dir",
 		absPath,
 		name,
-		realPath: await realpath(absPath)
+		realPath: await fsGate.run(() => realpath(absPath))
 	};
 	return SKIP;
 }
 async function readPage(filePath, name, dirSegments, config) {
-	const raw = await readFile(filePath, "utf8");
+	const raw = await fsGate.run(() => readFile(filePath, "utf8"));
 	const relativePath = toPosix(path.relative(config.contentDir, filePath));
 	let data;
 	let content;
+	let frontmatterLines = 0;
 	try {
-		const file = new VFile({ value: raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw });
+		const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+		const file = new VFile({ value: source });
 		matter(file, { strip: true });
 		data = file.data.matter;
 		content = String(file);
+		if (source.endsWith(content)) frontmatterLines = source.slice(0, source.length - content.length).split("\n").length - 1;
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		throw docsError("invalid-frontmatter", `Could not parse the frontmatter block in ${relativePath}: ${reason}`, { cause: err });
@@ -253,7 +322,8 @@ async function readPage(filePath, name, dirSegments, config) {
 			filePath,
 			relativePath,
 			frontmatter,
-			content
+			content,
+			frontmatterLines
 		}
 	};
 }
@@ -409,7 +479,7 @@ function toHref(basePath, segments) {
 	return `${basePath}/${encodeSegments(segments)}`;
 }
 function normalizeBasePath(basePath) {
-	const trimmed = basePath.trim().replace(/\/+$/, "");
+	const trimmed = basePath.trim().replace(/\/{2,}/g, "/").replace(/\/+$/, "");
 	if (trimmed === "") return "";
 	return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }

package/dist/styles.css

@@ -1844,6 +1844,19 @@
     z-index: 50;
     display: flex;
     justify-content: center;
+    /*
+     * ⚠️ `flex-start`, OR THE DIALOG IS ALWAYS 32rem TALL. A flex container
+     * defaults to `align-items: stretch`, so the dialog stretched to the full
+     * viewport height and `max-height` then capped it — at a constant. Measured
+     * before this line: 514px with no query, 514px with eight results, 514px
+     * with none, of which 392px was an empty results area. The reader typed
+     * into a box floating at the top of a large blank rectangle.
+     *
+     * Aligned to the start, the dialog is as tall as its content and the
+     * `max-height` below goes back to being what it says it is — a ceiling
+     * where the list starts scrolling, not a height.
+     */
+    align-items: flex-start;
     /* Not centred: a dialog that grows downward from a fixed top does not
      * shift under the reader as results stream in. */
     /* `dvh`, not `vh`: on a phone `vh` is the viewport with the URL bar
@@ -1930,12 +1943,29 @@
     border-color: var(--wave-docs-border-strong);
   }
 
+  /*
+   * `1 1 auto` and not `0 1 auto`: once the dialog hits its `max-height` this
+   * is the part that must take the remaining space and scroll, rather than the
+   * list overflowing a box sized to the input. With the dialog content-sized
+   * there is no free space to grow into, so it only bites at the ceiling —
+   * which is exactly when it should.
+   */
   .wave-docs-search-results {
     flex: 1 1 auto;
     overflow-y: auto;
     padding: 0.375rem;
   }
 
+  /*
+   * An empty results container has no padding to contribute. Without this it
+   * adds 12px of nothing under the input on every keystroke that matches
+   * nothing — small, and precisely the sort of gap that reads as a broken
+   * layout rather than as an empty state.
+   */
+  .wave-docs-search-results:empty {
+    display: none;
+  }
+
   .wave-docs-search-result {
     border-radius: var(--wave-docs-radius-sm);
   }
@@ -1969,20 +1999,39 @@
     line-height: 1.4;
   }
 
-  .wave-docs-search-result-breadcrumb {
-    color: var(--wave-docs-fg-subtle);
-    font-size: 0.75rem;
-    line-height: 1.4;
-  }
-
-  /* A crumb never wraps mid-title: the trail reads as a path or not at all.
-   * The breadcrumb line itself is free to wrap between crumbs. */
-  .wave-docs-search-result-crumb {
+  /*
+   * Where the hit lands, as a route.
+   *
+   * ⚠️ RENAMED FROM `…-breadcrumb` / `…-crumb`, WHICH IS BREAKING AND
+   * DELIBERATE. This used to be a trail of human names — "Installation ›
+   * Requirements" — and a page's own record, whose heading IS its page title,
+   * got no line at all rather than repeat itself. That left a list where some
+   * rows had two lines and some had one.
+   *
+   * The first repair gave those rows the route and kept the trail on the
+   * others, which was worse: one slot carrying two different kinds of thing,
+   * so "Styling" under one row was a page and "/docs/styling" under the next
+   * was an address. Now every row shows the route, always, and the class is
+   * named for what it holds — a breadcrumb it is not.
+   *
+   * The words live in the option's `aria-label`, because a route read aloud is
+   * punctuation.
+   */
+  .wave-docs-search-result-location {
+    display: block;
+    /* One line, ellipsised. A real site's routes reach
+     * `/docs/api/reference/authentication#rotating-keys`, and a wrapped route
+     * makes the row two different heights depending on its depth — the raggedness
+     * this whole change exists to remove. */
+    overflow: hidden;
     white-space: nowrap;
-  }
-
-  .wave-docs-search-result-crumb-separator {
-    margin-inline: 0.25rem;
+    text-overflow: ellipsis;
+    color: var(--wave-docs-fg-subtle);
+    font-family: var(--wave-docs-font-mono);
+    /* Smaller than the trail was: a monospace face reads larger at the same
+     * size, and this line is a reference rather than something to read. */
+    font-size: 0.6875rem;
+    line-height: 1.5;
   }
 
   .wave-docs-search-status {

package/dist/types.d.ts

@@ -67,6 +67,24 @@ interface DocFile<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
   frontmatter: TFrontmatter;
   /** Markdown body with the frontmatter block removed. */
   content: string;
+  /**
+   * How many lines the frontmatter block took up, so an error can name the line
+   * in the file rather than in the body.
+   *
+   * ⚠️ WITHOUT IT, EVERY LINK ERROR POINTED INTO THE FRONTMATTER. `content` has
+   * the block removed, so remark counts `node.position.start.line` from the
+   * first line of the *body* — and `broken-link`, `draft-link` and `alias-link`
+   * all report `relativePath:line`, the exact `file:line` form a terminal and an
+   * editor turn into a jump. A page with four frontmatter fields is six lines
+   * out: a link on line 10 was reported at line 4, which is the middle of the
+   * block that was deleted.
+   *
+   * Set by `@waveso/docs/source`. Optional and treated as `0` when absent,
+   * because a host loading content itself — the documented reason `./render` is
+   * an entry point — hands over a body with no block in front of it and has
+   * nothing to offset.
+   */
+  frontmatterLines?: number | undefined;
 }
 /** A link to a documentation page. */
 interface DocNavPage {
@@ -257,6 +275,18 @@ href: string, from: DocLinkContext) => string | undefined;
  * blindly prefixes what it is handed produces `/cdn//logo.png` and
  * `/cdn/https://example.com/a.png`. Branch on them, or return `undefined` to
  * leave the src as authored.
+ *
+ * ⚠️ IT IS A FILE PATH, NOT AN HREF. `src` is percent-decoded, so
+ * `./getting%20started.png` — what GitHub's editor writes when you drag in a
+ * file whose name has a space — arrives as `getting started.png`, the name that
+ * is actually on disk. Any `?query` and `#fragment` are split off before the
+ * call and re-attached to whatever you return, so `./diagram.png?v=2` arrives
+ * as `diagram.png` and the reader still gets the `?v=2`. Return a src carrying
+ * a query or a fragment of your own and yours is kept instead, because two `?`
+ * in one URL is not a URL.
+ *
+ * All three used to be handed over raw, and `readFile(join(dir, src))` — the
+ * implementation the README gives — threw `ENOENT` on every one of them.
  */
 type ImageResolver = (src: string, from: DocLinkContext) => Promise<{
   src: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [