@waveso/docs 0.3.0 → 0.5.0

package/dist/next.d.ts

@@ -1,7 +1,8 @@
 import { DocFile, DocFrontmatter, DocsConfig, ImageResolver, LinkResolver, RenderedDoc, SearchRecord } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.js";
-import { MarkdownComponents } from "./react/markdown-components.js";
+import { SerializableSearchOptions } from "./search-options.js";
 import { DocsLabels } from "./react/shell-labels.js";
+import { MarkdownComponents } from "./react/markdown-components.js";
 import { DocsLayoutSearchProps } from "./react/layout.js";
 import { DocsSource } from "./source.js";
 import { ReactNode } from "react";
@@ -61,13 +62,36 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
   /**
    * MiniSearch overrides for the index {@link DocsRoute.searchIndex} builds.
    *
-   * ⚠️ THE IDENTICAL OBJECT MUST REACH THE DIALOG — pass it to `DocsSearch`'s
-   * (or `SearchDialog`'s) `miniSearchOptions`. MiniSearch reads `tokenize` and
-   * `processTerm` both when indexing and when querying, so applying one here
-   * and not there produces an index whose terms no query can spell: zero
+   * ⚠️ THE IDENTICAL OBJECT MUST REACH THE DIALOG. MiniSearch reads `tokenize`
+   * and `processTerm` both when indexing and when querying, so applying one
+   * here and not there produces an index whose terms no query can spell: zero
    * results, no error, nothing in the console.
+   *
+   * {@link DocsRoute.Layout} forwards this for you, which covers every
+   * serialisable override — `storeFields`, `boost`, `searchOptions.fuzzy`. It
+   * cannot forward a **function**: the dialog is a Client Component and props
+   * crossing that boundary are serialised, so `tokenize`, `processTerm` and
+   * their kind make `next build` fail. Rather than drop them silently — which
+   * is the zero-results failure above, with the warning turned off — `Layout`
+   * throws `invalid-config` and names the remedy: pass `search={false}`, render
+   * `DocsSearch` from a `'use client'` module of your own, and import the same
+   * function there. See {@link SerializableSearchOptions}.
    */
   miniSearchOptions?: Partial<Options<SearchRecord>> | undefined;
+  /**
+   * Every string this package renders that is not your content.
+   *
+   * ⚠️ THE ROUTE IS WHERE THEY BELONG, BECAUSE THEY DO NOT ALL LIVE IN ONE
+   * RUNTIME. Four are rendered by the shell, two by the table of contents, nine
+   * by the markdown component map, two by a client-side copy runtime — and two
+   * are baked into the HTML by a rehype plugin at build time. `docs.Layout` can
+   * reach the first four and no more, which is exactly why its own `labels` prop
+   * documented itself as the whole set and covered less than a fifth of it.
+   *
+   * `docs.Layout` forwards these for you, and its `labels` prop still overrides
+   * them per-layout. Set them once here.
+   */
+  labels?: DocsLabels | undefined;
 }
 /**
  * Props for {@link DocsRoute.Layout}.
@@ -97,23 +121,39 @@ interface DocsLayoutProps {
    * The search trigger. Defaults to on, and the URL is always derived.
    *
    * `false` omits it. An object configures the dialog — `placeholder`,
-   * `hotkey`, `miniSearchOptions` and the rest of `DocsSearch`'s surface,
-   * minus `indexUrl`.
+   * `pageSize`, `minQueryLength`, the state messages and the rest of
+   * `DocsSearch`'s surface, minus `indexUrl`.
+   *
+   * (It used to say `hotkey`. There is no such prop and there never was: the
+   * shortcut is ⌘K / Ctrl-K and is not configurable. A docstring naming an
+   * option that does not exist is worse than one naming none.)
    *
    * You do not need to pass `miniSearchOptions` here to match what
    * `createDocsRoute` was given: the route's own value is forwarded, so the
    * object that built the index is the object that queries it. Pass one only
    * to override that.
+   *
+   * Serialisable overrides only, in both directions. This is a Server
+   * Component handing props to a Client one, so a `tokenize` or a
+   * `processTerm` here does not compile and one on the route throws rather
+   * than being quietly dropped — {@link SerializableSearchOptions} has the
+   * `'use client'` recipe for those.
    */
   search?: boolean | DocsLayoutSearchProps | undefined;
   /**
-   * The four strings the shell renders itself: the navigation landmark's name,
-   * the drawer's open and close buttons, and the skip link.
+   * Overrides for the strings the shell renders, over the route's.
+   *
+   * ⚠️ THIS DOCSTRING USED TO CLAIM TO BE "THE WHOLE OF WHAT A NON-ENGLISH SITE
+   * HAS TO SAY" AND REACHED FOUR STRINGS OF TWENTY-TWO. It could not have
+   * reached the rest: the table of contents is rendered by `docs.Page`, the
+   * callout headings by a component map built when the route is created, and the
+   * copy button is baked into the HTML by a rehype plugin at build time. None of
+   * those is downstream of a layout prop.
    *
-   * Everything else a reader sees is your markdown or your `title`. This is the
-   * whole of what a non-English site has to say — and it is the fifth prop,
-   * added deliberately: a documentation shell nobody can translate is not a
-   * shell for the whole ecosystem.
+   * So the set lives on {@link DocsRouteOptions.labels}, which is upstream of
+   * all four runtimes, and this overrides it key by key — for a site with two
+   * shells, or a section in another language. Whole-object replacement would
+   * mean naming one string cost you the other twenty-one.
    */
   labels?: DocsLabels | undefined;
 }
@@ -400,4 +440,4 @@ interface DocsRedirect {
  */
 declare function createDocsRedirects(config: DocsConfig): Promise<DocsRedirect[]>;
 //#endregion
-export { type DocsLang, DocsLayoutProps, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, createDocsRedirects, createDocsRoute, createDocsSitemap };
+export { type DocsLang, DocsLayoutProps, type DocsLayoutSearchProps, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, type SerializableSearchOptions, createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/next.js

@@ -1,6 +1,7 @@
 import { docsError } from "./docs-error.js";
 import { DOCS_CONTENT_ID } from "./docs-content-id.js";
 import { mapPooled } from "./map-pooled.js";
+import { findFunctionValuedOptions } from "./search-options.js";
 import { createMarkdownComponents } from "./react/markdown-components.js";
 import { DocContent } from "./react/doc-content.js";
 import { DocsToc } from "./react/toc.js";
@@ -119,9 +120,14 @@ async function loadNotFound() {
 * as `number | \`${number}\``, and spreading a `ComponentProps<'img'>`-shaped
 * object into it fails with TS2322 because the DOM types allow a bare `string`.
 * The build-time {@link ImageResolver} has already produced real numbers here.
+*
+* ⚠️ SO THE LIST IS THE CONTRACT, AND IT HAS TO MATCH `DocsImageProps`. A prop
+* added there and forgotten here is dropped silently — which is what happened to
+* `decoding` and `fetchPriority`, under a comment in `createImage` promising
+* they survived.
 */
 function wrapNextImage(NextImage) {
-	return function DocsNextImage({ src, alt, width, height, title, className, sizes, loading }) {
+	return function DocsNextImage({ src, alt, width, height, title, className, sizes, loading, decoding, fetchPriority }) {
 		return createElement(NextImage, {
 			src,
 			alt,
@@ -130,35 +136,92 @@ function wrapNextImage(NextImage) {
 			...title === void 0 ? {} : { title },
 			...className === void 0 ? {} : { className },
 			...sizes === void 0 ? {} : { sizes },
-			...loading === void 0 ? {} : { loading }
+			...loading === void 0 ? {} : { loading },
+			...decoding === void 0 ? {} : { decoding },
+			...fetchPriority === void 0 ? {} : { fetchPriority }
 		});
 	};
 }
 /**
-* The component map is built once per process.
+* A memo for the component map, one per route.
 *
 * `createMarkdownComponents` returns fresh component identities on every call,
 * and a new identity for `a` remounts every link in the document on every
 * render — so this memo is correctness, not micro-optimisation.
+*
+* ⚠️ PER ROUTE, NOT PER PROCESS, SINCE THE MAP CLOSES OVER THE ROUTE'S LABELS.
+* A single process-wide memo would hand the second route the first route's
+* language. Nothing is lost: `import()` caches the `next/link` and `next/image`
+* modules itself, so all a second route pays for is two wrapper identities —
+* and a route's identities only ever have to be stable against themselves,
+* because the pages that use them come from that same route.
 */
-let nextComponents = null;
-function loadNextComponents() {
-	if (nextComponents === null) nextComponents = buildNextComponents().catch((error) => {
-		nextComponents = null;
-		throw error;
-	});
-	return nextComponents;
+function createComponentsMemo(labels) {
+	let memo = null;
+	return () => {
+		if (memo === null) memo = buildNextComponents(labels).catch((error) => {
+			memo = null;
+			throw error;
+		});
+		return memo;
+	};
 }
-async function buildNextComponents() {
+async function buildNextComponents(labels) {
 	const [linkMod, imageMod] = await Promise.all([importNext(() => import("next/link"), "next/link"), importNext(() => import("next/image"), "next/image")]);
 	const NextLink = readDefaultExport(linkMod, "next/link");
 	const NextImage = readDefaultExport(imageMod, "next/image");
 	return createMarkdownComponents({
 		Link: wrapNextLink(NextLink),
-		Image: wrapNextImage(NextImage)
+		Image: wrapNextImage(NextImage),
+		...labels === void 0 ? {} : { labels }
 	});
 }
 /**
+* The named subset of `labels`, or `undefined` when none of it is set.
+*
+* `undefined` rather than `{}` is the point: every forwarding site here spreads
+* with `...(x === undefined ? {} : { x })`, so an empty object would still add a
+* prop — and for the two groups that cross a client boundary that is a prop in
+* every page's payload, forever, saying nothing.
+*
+* `map` goes target-key → `DocsLabels` key, so the rename is visible at the call
+* site rather than hidden in a component.
+*/
+function pickLabels(labels, map) {
+	if (labels === void 0) return void 0;
+	const picked = {};
+	let found = false;
+	for (const [target, source] of Object.entries(map)) {
+		const value = labels[source];
+		if (value !== void 0) {
+			picked[target] = value;
+			found = true;
+		}
+	}
+	return found ? picked : void 0;
+}
+/**
+* `candidate`, once it is known to hold no functions.
+*
+* The cast at the end is the whole point of the function, and
+* {@link findFunctionValuedOptions} is what earns it: a structural walk over
+* the values, so it answers for options MiniSearch has not shipped yet as well
+* as the five it has. `SerializableSearchOptions` narrows the same thing at
+* compile time, which is friendlier and strictly weaker — a JavaScript caller
+* has no types at all, and an `Omit` list goes stale the minor MiniSearch adds
+* a callback.
+*
+* Throwing beats dropping. Silently forwarding the serialisable half would
+* rebuild the original defect this channel exists to close — an index built
+* with a `processTerm` the query does not share returns nothing, reports
+* nothing, and looks like an empty corpus.
+*/
+function serializableSearchOptions(candidate) {
+	const functions = findFunctionValuedOptions(candidate);
+	if (functions.length > 0) throw docsError("invalid-config", `the search dialog cannot be given MiniSearch functions from a server component: ${functions.map((name) => `\`miniSearchOptions.${name}\``).join(", ")}. \`docs.Layout\` renders the dialog as a client component, so its props are serialised on the way across and React rejects a function with "Functions cannot be passed directly to Client Components" while prerendering. Keep the function on \`createDocsRoute\` so the index is still built with it, pass \`search={false}\` to \`docs.Layout\`, and render the dialog yourself from a \`'use client'\` module that imports the same function — \`<DocsSearch indexUrl={docs.searchIndexUrl} miniSearchOptions={{ processTerm }} />\` — putting that component in \`actions\`. Serialisable overrides (\`storeFields\`, \`boost\`, \`searchOptions.fuzzy\`) need none of this and are forwarded as before.`);
+	return candidate;
+}
+/**
 * Create the route handlers for a documentation tree.
 *
 * Call it once at module scope in each of the two route files. The filesystem
@@ -170,6 +233,28 @@ function createDocsRoute(options) {
 	const source = createDocsSource(options);
 	const siteUrl = normalizeSiteUrl(options.siteUrl);
 	const rescanPerRequest = process.env.NODE_ENV !== "production";
+	const routeLabels = options.labels;
+	const codeLabels = pickLabels(routeLabels, {
+		copyLabel: "copyCode",
+		copyFromLabel: "copyCodeFrom"
+	});
+	const contentLabels = pickLabels(routeLabels, {
+		externalLink: "externalLink",
+		table: "table",
+		calloutNote: "calloutNote",
+		calloutTip: "calloutTip",
+		calloutImportant: "calloutImportant",
+		calloutWarning: "calloutWarning",
+		calloutCaution: "calloutCaution",
+		youtubeTitle: "youtubeTitle",
+		youtubePlay: "youtubePlay",
+		youtubeHide: "youtubeHide"
+	});
+	const copyLabels = pickLabels(routeLabels, {
+		copied: "copied",
+		copyFailed: "copyFailed"
+	});
+	const loadComponents = createComponentsMemo(contentLabels);
 	let renderer = null;
 	const knownRoutes = /* @__PURE__ */ new Set();
 	const draftRoutes = /* @__PURE__ */ new Set();
@@ -232,6 +317,7 @@ function createDocsRoute(options) {
 		...options.langs === void 0 ? {} : { langs: options.langs },
 		...options.themes === void 0 ? {} : { themes: options.themes },
 		...options.excludeLangs === void 0 ? {} : { excludeLangs: options.excludeLangs },
+		...codeLabels === void 0 ? {} : { codeLabels },
 		...options.titleHeading === void 0 ? {} : { titleHeading: options.titleHeading },
 		...options.remarkPlugins === void 0 ? {} : { remarkPlugins: options.remarkPlugins },
 		...options.rehypePlugins === void 0 ? {} : { rehypePlugins: options.rehypePlugins },
@@ -321,7 +407,7 @@ function createDocsRoute(options) {
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
-		const components = await loadNextComponents();
+		const components = await loadComponents();
 		return createElement(Fragment, null, createElement("main", {
 			className: "wave-docs-layout__main",
 			id: DOCS_CONTENT_ID,
@@ -331,8 +417,13 @@ function createDocsRoute(options) {
 			components: {
 				...components,
 				...options.components
-			}
-		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, { entries: doc.toc })));
+			},
+			...copyLabels === void 0 ? {} : { labels: copyLabels }
+		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, {
+			entries: doc.toc,
+			...routeLabels?.toc === void 0 ? {} : { label: routeLabels.toc },
+			...routeLabels?.backToTop === void 0 ? {} : { topLabel: routeLabels.backToTop }
+		})));
 	}
 	return {
 		source: requestScopedSource,
@@ -350,9 +441,15 @@ function createDocsRoute(options) {
 		},
 		async Layout({ children, title, actions, search, labels }) {
 			const { DocsLayoutShell } = await import("./react/layout.js");
+			const host = search === true || search === void 0 || search === false ? void 0 : search;
+			const requestedOptions = host?.miniSearchOptions ?? options.miniSearchOptions;
 			const searchProps = search === false ? false : {
-				...options.miniSearchOptions === void 0 ? {} : { miniSearchOptions: options.miniSearchOptions },
-				...search === true || search === void 0 ? {} : search
+				...host,
+				...requestedOptions === void 0 ? {} : { miniSearchOptions: serializableSearchOptions(requestedOptions) }
+			};
+			const shellLabels = options.labels === void 0 && labels === void 0 ? void 0 : {
+				...options.labels,
+				...labels
 			};
 			return createElement(DocsLayoutShell, {
 				children,
@@ -361,7 +458,7 @@ function createDocsRoute(options) {
 				search: searchProps,
 				...title === void 0 ? {} : { title },
 				...actions === void 0 ? {} : { actions },
-				...labels === void 0 ? {} : { labels }
+				...shellLabels === void 0 ? {} : { labels: shellLabels }
 			});
 		},
 		async generateStaticParams() {

package/dist/plugins/rehype-code-frame.d.ts

@@ -2,8 +2,20 @@ import { Plugin } from "unified";
 import { Root } from "hast";
 //#region src/plugins/rehype-code-frame.d.ts
 interface RehypeCodeFrameOptions {
-  /** Accessible name when a fence has no title. */
+  /**
+   * Accessible name of the copy button on a fence with no title.
+   * Default `'Copy code'`.
+   */
   copyLabel?: string | undefined;
+  /**
+   * The same button on a titled fence. Default `'Copy code from {title}'`.
+   *
+   * `{title}` is replaced with the fence's own `title="…"`. Two controls both
+   * called "Copy code" are indistinguishable in a screen reader's element list,
+   * which is why the titled form exists at all — and a translator needs to be
+   * able to move the title within the sentence, which concatenation forbade.
+   */
+  copyFromLabel?: string | undefined;
 }
 declare const rehypeCodeFrame: Plugin<[RehypeCodeFrameOptions?], Root>;
 //#endregion

package/dist/plugins/rehype-code-frame.js

@@ -6,6 +6,7 @@ import { CONTINUE, SKIP, visit } from "unist-util-visit";
 const LANGUAGE_CLASS = /^language-(.+)$/;
 const rehypeCodeFrame = (options = {}) => {
 	const copyLabel = options.copyLabel ?? "Copy code";
+	const copyFromLabel = options.copyFromLabel ?? "Copy code from {title}";
 	return (tree, file) => {
 		const path = file.data.docLinkContext?.relativePath ?? file.path ?? "a document";
 		visit(tree, "element", (node, index, parent) => {
@@ -27,7 +28,7 @@ const rehypeCodeFrame = (options = {}) => {
 					value: title
 				}]
 			});
-			children.push(copyButton(title === void 0 ? copyLabel : `${copyLabel} from ${title}`), node);
+			children.push(copyButton(title === void 0 ? copyLabel : copyFromLabel.replace("{title}", title)), node);
 			parent.children[index] = {
 				type: "element",
 				tagName: "figure",

package/dist/plugins/remark-doc-links.d.ts

@@ -56,6 +56,56 @@ interface RemarkDocLinksOptions {
  * are contained by one implementation rather than two.
  */
 declare function foldSegments(from: readonly string[], path: string): string[] | undefined;
+/**
+ * Decode BEFORE folding, never after: `%2E%2E%2F` is `../` in disguise, and
+ * `foldSegments` is the only thing that refuses a chain climbing out of the
+ * content root.
+ *
+ * Exported for `route-path.ts`, which needs the decode without the split:
+ * an alias may carry a literal `#` or `?` — `c# guide` is a page name — and
+ * {@link splitHref} would cut the string there and throw the rest away.
+ */
+declare function decodePath(path: string, href: string): string;
+/**
+ * An href, split at `?` and `#`, with the path decoded and the rest left alone.
+ *
+ * ⚠️ ONE IMPLEMENTATION, BECAUSE THE THIRD COPY WAS WRONG. Four call sites need
+ * this exact sequence — split, decode the path, fold, re-attach — and three of
+ * them had it inline while `foldImageSrc` in `render.ts` had none of it. An
+ * author dragging a file into GitHub's editor gets `![a](./getting%20started.png)`
+ * written for them, and that reached the resolver undecoded: `readFile` on a
+ * filename with a literal `%20` in it, `ENOENT`, and a build failed on an image
+ * that is plainly on disk and that GitHub renders. `./diagram.png?v=2` and
+ * `./sprite.svg#icon` baked the query and the fragment into the filename the
+ * same way.
+ *
+ * A query and a fragment are never decoded: `?q=a%26b` carries a literal
+ * ampersand that decoding would turn into a separator, and neither is part of
+ * any filename.
+ */
+interface HrefParts {
+  /** Path, percent-decoded and NFC-normalised — what {@link foldSegments} needs. */
+  path: string;
+  /**
+   * The same span exactly as authored.
+   *
+   * One caller needs it: {@link normalizeInternalRoute} strips `basePath` off
+   * the front by length, and doing that to a decoded path would cut at the
+   * wrong offset for any href that percent-encoded part of the prefix.
+   */
+  rawPath: string;
+  /** `?query` as authored, or `''`. */
+  query: string;
+  /** `#hash` as authored, or `''`. */
+  hash: string;
+}
+/**
+ * Split an href into its path, query and fragment; decode only the path.
+ *
+ * Throws a {@link URIError} if the path is not valid percent-encoding, with the
+ * whole href in the message — see {@link decodeSegment}.
+ */
+declare function splitHref(href: string): HrefParts;
 /**
  * The built-in {@link LinkResolver}: markdown file path in, route out.
  *
@@ -71,4 +121,4 @@ declare function resolveMarkdownLink(href: string, fromDir: readonly string[], b
  */
 declare const remarkDocLinks: Plugin<[RemarkDocLinksOptions], Root>;
 //#endregion
-export { type DocLinkContext, DocLinkRef, RemarkDocLinksOptions, foldSegments, remarkDocLinks, resolveMarkdownLink };
+export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };

package/dist/plugins/remark-doc-links.js

@@ -107,11 +107,31 @@ function decodeSegment(segment, href) {
 * Decode BEFORE folding, never after: `%2E%2E%2F` is `../` in disguise, and
 * `foldSegments` is the only thing that refuses a chain climbing out of the
 * content root.
+*
+* Exported for `route-path.ts`, which needs the decode without the split:
+* an alias may carry a literal `#` or `?` — `c# guide` is a page name — and
+* {@link splitHref} would cut the string there and throw the rest away.
 */
 function decodePath(path, href) {
 	return path.split("/").map((segment) => decodeSegment(segment, href)).join("/");
 }
 /**
+* Split an href into its path, query and fragment; decode only the path.
+*
+* Throws a {@link URIError} if the path is not valid percent-encoding, with the
+* whole href in the message — see {@link decodeSegment}.
+*/
+function splitHref(href) {
+	const parts = HREF_PARTS.exec(href);
+	const rawPath = parts?.[1] ?? "";
+	return {
+		path: decodePath(rawPath, href),
+		rawPath,
+		query: parts?.[2] ?? "",
+		hash: parts?.[3] ?? ""
+	};
+}
+/**
 * The built-in {@link LinkResolver}: markdown file path in, route out.
 *
 * Exported for reuse by hosts that want to wrap rather than replace it. Throws
@@ -119,12 +139,9 @@ function decodePath(path, href) {
 * reported as `undefined`.
 */
 function resolveMarkdownLink(href, fromDir, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
+	const { path, query, hash } = splitHref(href);
 	if (path === "") return;
-	const segments = foldSegments(fromDir, decodePath(path, href));
+	const segments = foldSegments(fromDir, path);
 	if (segments === void 0) return;
 	const last = segments.at(-1);
 	if (last !== void 0) {
@@ -149,12 +166,9 @@ function resolveMarkdownLink(href, fromDir, basePath) {
 * browser resolves happily and `knownRoutes` has never heard of.
 */
 function normalizeInternalRoute(href, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
+	const { rawPath, query, hash } = splitHref(href);
 	const base = basePath.replace(/\/+$/, "");
-	const segments = foldSegments([], decodePath(path.slice(base.length), href));
+	const segments = foldSegments([], decodePath(rawPath.slice(base.length), href));
 	if (segments === void 0) return;
 	return `${toRoute(basePath, segments)}${query}${hash}`;
 }
@@ -183,11 +197,8 @@ function isAssetLink(href) {
 * the exception.
 */
 function resolveAssetLink(href, fromDir, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
-	const segments = foldSegments(fromDir, decodePath(path, href));
+	const { path, query, hash } = splitHref(href);
+	const segments = foldSegments(fromDir, path);
 	if (segments === void 0) return;
 	return `${toRoute(basePath, segments)}${query}${hash}`;
 }
@@ -246,4 +257,4 @@ const remarkDocLinks = (options) => {
 	};
 };
 //#endregion
-export { foldSegments, remarkDocLinks, resolveMarkdownLink };
+export { decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };

package/dist/plugins/remark-youtube.d.ts

@@ -1,13 +1,28 @@
 import { Plugin } from "unified";
 import { Root } from "mdast";
 //#region src/plugins/remark-youtube.d.ts
+/** What a YouTube URL says, beyond which video it is. */
+interface YouTubeRef {
+  id: string;
+  /** Seconds to start at, from `t` or `start`. */
+  start?: number | undefined;
+  /** Playlist the video was linked inside, from `list`. */
+  list?: string | undefined;
+}
 /**
- * Extract a video id from a YouTube watch/short/embed URL.
+ * Extract a video reference from a YouTube watch/short/embed URL.
  *
  * Returns `undefined` for anything else, including YouTube URLs that are not a
  * single video (channels, playlists) — those stay ordinary links.
+ *
+ * ⚠️ THE TIMESTAMP AND THE PLAYLIST ARE PART OF THE LINK, AND WERE DROPPED. Only
+ * the id survived, so `https://youtu.be/x?t=754` — a link to one specific moment
+ * in a two-hour talk, which is most of why anyone deep-links a video — opened at
+ * zero. And because the facade passes `autoplay=1`, it did not merely start in
+ * the wrong place: it started *playing* in the wrong place, so the reader had to
+ * work out that the author had meant somewhere else.
  */
-declare function parseYouTubeId(href: string): string | undefined;
+declare function parseYouTubeRef(href: string): YouTubeRef | undefined;
 /**
  * remark plugin. Replaces the whole PARAGRAPH, not the link inside it — which
  * is the point: leaving the paragraph is what nested a block element in
@@ -19,4 +34,4 @@ declare function parseYouTubeId(href: string): string | undefined;
  */
 declare const remarkYouTube: Plugin<[], Root>;
 //#endregion
-export { parseYouTubeId, remarkYouTube };
+export { YouTubeRef, parseYouTubeRef, remarkYouTube };

package/dist/plugins/remark-youtube.js

@@ -4,13 +4,40 @@ import { SKIP, visit } from "unist-util-visit";
 const VIDEO_ID = /^[A-Za-z0-9_-]{11}$/;
 /** `https://` or `http://`, for comparing a label against its own href. */
 const HTTP_SCHEME = /^https?:\/\//i;
+/** A playlist id, conservatively: what YouTube uses and nothing else. */
+const PLAYLIST_ID = /^[A-Za-z0-9_-]{2,64}$/;
 /**
-* Extract a video id from a YouTube watch/short/embed URL.
+* `1h2m3s`, `90s`, `90` — every spelling YouTube's own `t` parameter takes.
+*/
+const TIMESTAMP = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s?)?$/;
+/**
+* Seconds from a `t`/`start` value, or `undefined` if it is not one.
+*
+* YouTube accepts `t=90`, `t=90s` and `t=1m30s`, and an author linking to a
+* moment in a talk pastes whichever the share dialog gave them.
+*/
+function parseTimestamp(value) {
+	if (value === null || value === "") return void 0;
+	const match = TIMESTAMP.exec(value);
+	if (match === null) return void 0;
+	const [, hours, minutes, seconds] = match;
+	const total = Number(hours ?? 0) * 3600 + Number(minutes ?? 0) * 60 + Number(seconds ?? 0);
+	return Number.isFinite(total) && total > 0 ? total : void 0;
+}
+/**
+* Extract a video reference from a YouTube watch/short/embed URL.
 *
 * Returns `undefined` for anything else, including YouTube URLs that are not a
 * single video (channels, playlists) — those stay ordinary links.
+*
+* ⚠️ THE TIMESTAMP AND THE PLAYLIST ARE PART OF THE LINK, AND WERE DROPPED. Only
+* the id survived, so `https://youtu.be/x?t=754` — a link to one specific moment
+* in a two-hour talk, which is most of why anyone deep-links a video — opened at
+* zero. And because the facade passes `autoplay=1`, it did not merely start in
+* the wrong place: it started *playing* in the wrong place, so the reader had to
+* work out that the author had meant somewhere else.
 */
-function parseYouTubeId(href) {
+function parseYouTubeRef(href) {
 	let url;
 	try {
 		url = new URL(href, "https://example.invalid");
@@ -19,17 +46,34 @@ function parseYouTubeId(href) {
 	}
 	const host = url.hostname.replace(/^(www|m)\./, "");
 	const segments = url.pathname.split("/").filter(Boolean);
+	const extras = () => {
+		const start = parseTimestamp(url.searchParams.get("t")) ?? parseTimestamp(url.searchParams.get("start")) ?? parseTimestamp(url.hash.replace(/^#t=/, "") || null);
+		const list = url.searchParams.get("list");
+		return {
+			...start === void 0 ? {} : { start },
+			...list !== null && PLAYLIST_ID.test(list) ? { list } : {}
+		};
+	};
 	if (host === "youtu.be") {
 		const [id] = segments;
-		return id !== void 0 && VIDEO_ID.test(id) ? id : void 0;
+		return id !== void 0 && VIDEO_ID.test(id) ? {
+			id,
+			...extras()
+		} : void 0;
 	}
 	if (host !== "youtube.com" && host !== "youtube-nocookie.com") return;
 	if (url.pathname === "/watch") {
 		const id = url.searchParams.get("v");
-		return id !== null && VIDEO_ID.test(id) ? id : void 0;
+		return id !== null && VIDEO_ID.test(id) ? {
+			id,
+			...extras()
+		} : void 0;
 	}
 	const [prefix, id] = segments;
-	if ((prefix === "embed" || prefix === "shorts") && id !== void 0) return VIDEO_ID.test(id) ? id : void 0;
+	if ((prefix === "embed" || prefix === "shorts") && id !== void 0) return VIDEO_ID.test(id) ? {
+		id,
+		...extras()
+	} : void 0;
 }
 /** Whitespace-only text is what separates two links on consecutive lines. */
 function isIgnorable(node) {
@@ -66,14 +110,18 @@ const remarkYouTube = () => {
 			const meaningful = node.children.filter((child) => !isIgnorable(child));
 			const only = meaningful[0];
 			if (meaningful.length !== 1 || only === void 0 || !isBareUrl(only)) return;
-			const id = only.type === "link" ? parseYouTubeId(only.url) : void 0;
-			if (id === void 0) return;
+			const ref = only.type === "link" ? parseYouTubeRef(only.url) : void 0;
+			if (ref === void 0) return;
 			parent.children[index] = {
 				type: "paragraph",
 				children: [],
 				data: {
 					hName: "youtube",
-					hProperties: { id }
+					hProperties: {
+						id: ref.id,
+						...ref.start === void 0 ? {} : { start: ref.start },
+						...ref.list === void 0 ? {} : { list: ref.list }
+					}
 				}
 			};
 			return [SKIP, index + 1];
@@ -81,4 +129,4 @@ const remarkYouTube = () => {
 	};
 };
 //#endregion
-export { parseYouTubeId, remarkYouTube };
+export { parseYouTubeRef, remarkYouTube };