@waveso/docs 0.4.0 → 0.6.0

package/dist/react/shell-labels.d.ts

@@ -1,22 +1,45 @@
 //#region src/react/shell-labels.d.ts
 /**
- * Every user-visible string the shell renders that is not the reader's content.
+ * Every user-visible string this package renders that is not the reader's
+ * content.
  *
- * ⚠️ THERE ARE ONLY FIVE, AND THAT IS THE POINT. `docs.Layout` renders the
- * whole chrome of a documentation site, and until this existed all five were
- * hardcoded English with no way to reach them: `DocsNav` declared `label` and
- * `closeLabel` props, documented them, defaulted them — and the layout that is
- * the only thing rendering `DocsNav` never passed either, while `DocsLayoutProps`
- * had no way to say them. Dead options that read as configuration.
+ * ⚠️ THERE USED TO BE FOUR, AND THE DOCSTRING CLAIMED THEY WERE ALL OF THEM.
+ * They were the four `docs.Layout` renders directly, and the claim — "the whole
+ * of what a non-English site has to say" — was false by seventeen strings. A
+ * German site built exactly the documented way shipped
+ * `<nav aria-label="On this page">`, a visible `Back to top`, `aria-label="Tip"`
+ * on every callout, `Copy code` on every fence and `(opens in a new tab)` after
+ * every external link. Verified in this repository's own `site/out`, which is
+ * how it was found.
  *
- * Private module, public type: `next.ts` re-exports {@link DocsLabels} as part
- * of `DocsLayoutProps`, and this file exists so the Node adapter can name the
- * type without importing a `'use client'` module for it.
+ * ## Where each one is rendered, because it decides the cost
+ *
+ * Most are emitted by Server Components or baked into the HTML by a rehype
+ * plugin at build time, so overriding them costs nothing at all. Six cross into
+ * a Client Component — the two sidebar disclosure verbs, the two table-of-contents
+ * strings and the two copy-status messages — and those are forwarded ONLY when
+ * set, so a site that overrides nothing carries exactly the payload it did
+ * before.
+ *
+ * ## The defaults do not all live here
+ *
+ * {@link DEFAULT_DOCS_LABELS} covers the four shell strings and no more, on
+ * purpose. The rest default inside the component that renders them, because
+ * this module would otherwise have to be imported by `sidebar.tsx` and
+ * `code-runtime.tsx` — and an object literal of twenty-one strings does not
+ * tree-shake, so every reader would download the German site's English
+ * fallbacks. `next.test.ts` asserts that every key here reaches the output, so
+ * a key that is declared and never wired fails rather than reading as
+ * configuration.
  *
  * Not here: the search dialog's strings, which are reachable through
- * `search={{ … }}`; and the sidebar's own `label`, which is public API on
- * `DocsSidebar` for anyone composing a shell by hand. This is the set that had
- * no route at all.
+ * `search={{ … }}` on `docs.Layout` — its trigger, its placeholder, its
+ * accessible name and its five state messages, plus the plural forms of its
+ * live region. They travel with the dialog's own props rather than with these
+ * because that channel already existed and already carries `pageSize` and
+ * `minQueryLength`; a second route to the same component would be two places to
+ * look. `DocsSidebar`'s own `label` is likewise public API, for anyone composing
+ * a shell by hand.
  */
 interface DocsLabels {
   /** The navigation landmark's accessible name. Default `'Documentation'`. */
@@ -27,17 +50,108 @@ interface DocsLabels {
   closeNav?: string | undefined;
   /** The skip link's visible text. Default `'Skip to content'`. */
   skipToContent?: string | undefined;
+  /**
+   * Accessible name of a collapsed group's toggle. Default `'Expand {title}'`.
+   *
+   * `{title}` is replaced with the group's own name. A placeholder rather than a
+   * function because this crosses from a Server Component to a Client one, where
+   * a function cannot go.
+   */
+  expandGroup?: string | undefined;
+  /** The same toggle when open. Default `'Collapse {title}'`. */
+  collapseGroup?: string | undefined;
+  /** The TOC landmark's accessible name. Default `'On this page'`. */
+  toc?: string | undefined;
+  /** The link at the end of the TOC. Default `'Back to top'`. */
+  backToTop?: string | undefined;
+  /**
+   * Screen-reader suffix on a link that opens a new tab.
+   * Default `'(opens in a new tab)'`.
+   */
+  externalLink?: string | undefined;
+  /**
+   * Accessible name of a wide table's scroll region. Default `'Table'`.
+   *
+   * The region exists so a keyboard user can scroll a table that overflows; an
+   * unnamed one is announced as "region", which says nothing about what it
+   * holds.
+   */
+  table?: string | undefined;
+  /** Heading on a `> [!NOTE]` callout. Default `'Note'`. */
+  calloutNote?: string | undefined;
+  /** Heading on a `> [!TIP]` callout. Default `'Tip'`. */
+  calloutTip?: string | undefined;
+  /** Heading on a `> [!IMPORTANT]` callout. Default `'Important'`. */
+  calloutImportant?: string | undefined;
+  /** Heading on a `> [!WARNING]` callout. Default `'Warning'`. */
+  calloutWarning?: string | undefined;
+  /** Heading on a `> [!CAUTION]` callout. Default `'Caution'`. */
+  calloutCaution?: string | undefined;
+  /**
+   * Accessible name of a YouTube embed. Default `'YouTube video player'`.
+   *
+   * Markdown carries no video title, so this is the name every embed on the site
+   * gets unless a `<YouTube title>` overrides it.
+   */
+  youtubeTitle?: string | undefined;
+  /**
+   * The closed facade's control. Default `'Play video: {title}'`.
+   *
+   * `{title}` is the embed's accessible name.
+   */
+  youtubePlay?: string | undefined;
+  /** The open facade's control. Default `'Hide video: {title}'`. */
+  youtubeHide?: string | undefined;
+  /** The copy button on a fence with no title. Default `'Copy code'`. */
+  copyCode?: string | undefined;
+  /**
+   * The copy button on a titled fence. Default `'Copy code from {title}'`.
+   *
+   * `{title}` is 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.
+   */
+  copyCodeFrom?: string | undefined;
+  /** Announced after a successful copy. Default `'Copied to the clipboard.'` */
+  copied?: string | undefined;
+  /**
+   * Announced after a failed one. Default
+   * `'Copy failed. Select the code and press Control or Command + C.'`
+   *
+   * Says what to do instead, not merely that it failed: the common way to land
+   * here is `next dev` on a phone over plain HTTP, where there is no secure
+   * context and retrying cannot help.
+   */
+  copyFailed?: string | undefined;
 }
 /**
- * The defaults, in one place.
+ * Every key of {@link DocsLabels}, for the test that proves each one is wired.
  *
- * A `Required<DocsLabels>` rather than four `=` defaults spread across three
- * components: the previous arrangement is how `DocsSidebar` came to default its
- * landmark to `'Docs'` while `DocsNav` defaulted the same landmark to
- * `'Documentation'` — two names for one region, depending on the viewport.
+ * A list rather than a type-level trick because the assertion has to run: the
+ * failure being guarded against is a key that is declared, documented and never
+ * read, which type-checks perfectly.
  */
-declare const DEFAULT_DOCS_LABELS: Required<DocsLabels>;
+declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "copied", "copyFailed"];
+/** The four the shell renders itself, resolved centrally. */
+type ShellLabelKey = 'nav' | 'openNav' | 'closeNav' | 'skipToContent';
+/**
+ * Defaults for the shell's four, in one place.
+ *
+ * A `Required<…>` rather than four `=` defaults spread across three components:
+ * the previous arrangement is how `DocsSidebar` came to default its landmark to
+ * `'Docs'` while `DocsNav` defaulted the same landmark to `'Documentation'` —
+ * two names for one region, depending on the viewport.
+ */
+declare const DEFAULT_DOCS_LABELS: Required<Pick<DocsLabels, ShellLabelKey>>;
 /** The given labels over the defaults, with `undefined` treated as unset. */
-declare function resolveLabels(labels: DocsLabels | undefined): Required<DocsLabels>;
+declare function resolveLabels(labels: DocsLabels | undefined): Required<Pick<DocsLabels, ShellLabelKey>>;
+/**
+ * `template` with `{title}` replaced.
+ *
+ * A placeholder, because these strings cross a Server → Client boundary where a
+ * function cannot go — and because a translator needs to move the name within
+ * the sentence, which string concatenation does not allow.
+ */
+declare function fillTitle(template: string, title: string): string;
 //#endregion
-export { DEFAULT_DOCS_LABELS, DocsLabels, resolveLabels };
+export { DEFAULT_DOCS_LABELS, DOCS_LABEL_KEYS, DocsLabels, ShellLabelKey, fillTitle, resolveLabels };

package/dist/react/shell-labels.js

@@ -1,11 +1,42 @@
 //#region src/react/shell-labels.ts
 /**
-* The defaults, in one place.
+* Every key of {@link DocsLabels}, for the test that proves each one is wired.
 *
-* A `Required<DocsLabels>` rather than four `=` defaults spread across three
-* components: the previous arrangement is how `DocsSidebar` came to default its
-* landmark to `'Docs'` while `DocsNav` defaulted the same landmark to
-* `'Documentation'` — two names for one region, depending on the viewport.
+* A list rather than a type-level trick because the assertion has to run: the
+* failure being guarded against is a key that is declared, documented and never
+* read, which type-checks perfectly.
+*/
+const DOCS_LABEL_KEYS = [
+	"nav",
+	"openNav",
+	"closeNav",
+	"skipToContent",
+	"expandGroup",
+	"collapseGroup",
+	"toc",
+	"backToTop",
+	"externalLink",
+	"table",
+	"calloutNote",
+	"calloutTip",
+	"calloutImportant",
+	"calloutWarning",
+	"calloutCaution",
+	"youtubeTitle",
+	"youtubePlay",
+	"youtubeHide",
+	"copyCode",
+	"copyCodeFrom",
+	"copied",
+	"copyFailed"
+];
+/**
+* Defaults for the shell's four, in one place.
+*
+* A `Required<…>` rather than four `=` defaults spread across three components:
+* the previous arrangement is how `DocsSidebar` came to default its landmark to
+* `'Docs'` while `DocsNav` defaulted the same landmark to `'Documentation'` —
+* two names for one region, depending on the viewport.
 */
 const DEFAULT_DOCS_LABELS = {
 	nav: "Documentation",
@@ -23,5 +54,15 @@ function resolveLabels(labels) {
 		skipToContent: labels.skipToContent ?? DEFAULT_DOCS_LABELS.skipToContent
 	};
 }
+/**
+* `template` with `{title}` replaced.
+*
+* A placeholder, because these strings cross a Server → Client boundary where a
+* function cannot go — and because a translator needs to move the name within
+* the sentence, which string concatenation does not allow.
+*/
+function fillTitle(template, title) {
+	return template.replace("{title}", title);
+}
 //#endregion
-export { DEFAULT_DOCS_LABELS, resolveLabels };
+export { DEFAULT_DOCS_LABELS, DOCS_LABEL_KEYS, fillTitle, resolveLabels };

package/dist/react/sidebar.d.ts

@@ -15,6 +15,23 @@ interface DocsSidebarProps {
   Link?: DocsLinkComponent | undefined;
   /** Accessible name for the landmark. Distinguish multiple navs on a page. */
   label?: string | undefined;
+  /**
+   * A collapsed group's toggle. Default `'Expand {title}'`.
+   *
+   * `{title}` is replaced with the group's own name. A placeholder rather than
+   * a function, because `docs.Layout` sets this from a Server Component and a
+   * function cannot cross that boundary — and because a translator has to be
+   * able to move the name within the sentence.
+   */
+  expandGroup?: string | undefined;
+  /** The same toggle when open. Default `'Collapse {title}'`. */
+  collapseGroup?: string | undefined;
+  /**
+   * Screen-reader suffix on an external link. Default `'(opens in a new tab)'`.
+   *
+   * The separating space is markup, so this is the sentence and nothing else.
+   */
+  externalLink?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -59,6 +76,6 @@ interface DocsSidebarProps {
  * nothing prefetches locally whatever this says. Do not "fix" it back because
  * the network tab looks the same.
  */
-declare function DocsSidebar({ nav, pathname, Link, label, className }: DocsSidebarProps): ReactNode;
+declare function DocsSidebar({ nav, pathname, Link, label, expandGroup, collapseGroup, externalLink, className }: DocsSidebarProps): ReactNode;
 //#endregion
 export { DocsSidebar, DocsSidebarProps };

package/dist/react/sidebar.js

@@ -1,8 +1,13 @@
 "use client";
 import { nearestScrollTop } from "./nearest-scroll-top.js";
-import { useId, useLayoutEffect, useRef, useState } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/sidebar.tsx
+const DEFAULT_SIDEBAR_LABELS = {
+	expandGroup: "Expand {title}",
+	collapseGroup: "Collapse {title}",
+	externalLink: "(opens in a new tab)"
+};
 /** Trailing slashes are a routing detail, not a difference in identity. */
 function normalizeHref(href) {
 	return href.length > 1 ? href.replace(/\/+$/, "") : href;
@@ -61,7 +66,12 @@ function containsActive(node, pathname) {
 * nothing prefetches locally whatever this says. Do not "fix" it back because
 * the network tab looks the same.
 */
-function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
+function DocsSidebar({ nav, pathname, Link, label = "Docs", expandGroup, collapseGroup, externalLink, className }) {
+	const text = {
+		expandGroup: expandGroup ?? DEFAULT_SIDEBAR_LABELS.expandGroup,
+		collapseGroup: collapseGroup ?? DEFAULT_SIDEBAR_LABELS.collapseGroup,
+		externalLink: externalLink ?? DEFAULT_SIDEBAR_LABELS.externalLink
+	};
 	const baseId = useId();
 	const [toggled, setToggled] = useState({});
 	const lastPathname = useRef(pathname);
@@ -77,19 +87,19 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 	};
 	const navRef = useRef(null);
 	useLayoutEffect(() => {
-		const active = navRef.current?.querySelector("[aria-current=\"page\"]");
-		if (!(active instanceof HTMLElement)) return;
-		const port = scrollableAncestor(active);
-		if (port === null) return;
-		const next = nearestScrollTop({
-			itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
-			itemHeight: active.offsetHeight,
-			viewHeight: port.clientHeight,
-			scrollTop: port.scrollTop,
-			scrollHeight: port.scrollHeight
-		});
-		if (next !== void 0) port.scrollTop = next;
+		revealActive(navRef.current);
 	}, [pathname]);
+	useEffect(() => {
+		const dialog = navRef.current?.closest("dialog");
+		if (!(dialog instanceof HTMLDialogElement)) return;
+		const onToggle = () => {
+			if (dialog.open) revealActive(navRef.current);
+		};
+		dialog.addEventListener("toggle", onToggle);
+		return () => {
+			dialog.removeEventListener("toggle", onToggle);
+		};
+	}, []);
 	return /* @__PURE__ */ jsx("nav", {
 		ref: navRef,
 		"aria-label": label,
@@ -101,7 +111,8 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 			pathname,
 			Link,
 			toggled,
-			onToggle: handleToggle
+			onToggle: handleToggle,
+			text
 		})
 	});
 }
@@ -115,6 +126,28 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 * one navigation where they know precisely what they asked for.
 * `sidebar.test.tsx` spies on it and asserts it is never called.
 */
+/**
+* Scroll the item marked `aria-current="page"` into view, if it is not already.
+*
+* A no-op wherever there is nothing to measure — no nav, no active item, no
+* scrollport — which is every server render, every jsdom render, and every
+* layout where the column is shorter than its content. Nothing to do, and
+* nothing to do wrongly.
+*/
+function revealActive(nav) {
+	const active = nav?.querySelector("[aria-current=\"page\"]");
+	if (!(active instanceof HTMLElement)) return;
+	const port = scrollableAncestor(active);
+	if (port === null) return;
+	const next = nearestScrollTop({
+		itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
+		itemHeight: active.offsetHeight,
+		viewHeight: port.clientHeight,
+		scrollTop: port.scrollTop,
+		scrollHeight: port.scrollHeight
+	});
+	if (next !== void 0) port.scrollTop = next;
+}
 function scrollableAncestor(element) {
 	let current = element.parentElement;
 	while (current !== null) {
@@ -124,7 +157,7 @@ function scrollableAncestor(element) {
 	}
 	return null;
 }
-function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, id }) {
+function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, text, id }) {
 	const holdsActive = nodes.some((node) => (node.type === "page" || node.type === "link" && !node.external) && isActiveHref(pathname, node.href));
 	return /* @__PURE__ */ jsx("ul", {
 		id,
@@ -148,6 +181,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						isActive: !node.external && isActiveHref(pathname, node.href),
 						isNearby: holdsActive,
 						Link,
+						externalLink: text.externalLink,
 						children: node.title
 					})
 				}, key);
@@ -169,14 +203,15 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 					pathname,
 					Link,
 					toggled,
-					onToggle
+					onToggle,
+					text
 				}, key);
 				default: return null;
 			}
 		})
 	});
 }
-function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
+function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, text }) {
 	const listId = `${itemKey}-list`;
 	const hasActive = containsActive(node, pathname);
 	const isOpen = toggled[itemKey] ?? hasActive;
@@ -208,7 +243,7 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 				className: "wave-docs-sidebar__group-toggle",
 				"aria-expanded": isOpen,
 				"aria-controls": isOpen ? listId : void 0,
-				"aria-label": `${isOpen ? "Collapse" : "Expand"} ${node.title}`,
+				"aria-label": (isOpen ? text.collapseGroup : text.expandGroup).replace("{title}", node.title),
 				onClick: () => onToggle(itemKey, !isOpen),
 				children: /* @__PURE__ */ jsx(Chevron, { isOpen })
 			})] })
@@ -220,11 +255,12 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 			pathname,
 			Link,
 			toggled,
-			onToggle
+			onToggle,
+			text
 		}) : null]
 	});
 }
-function NavLink({ href, isExternal, isActive, isNearby = false, Link, children }) {
+function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalLink = DEFAULT_SIDEBAR_LABELS.externalLink, children }) {
 	const className = "wave-docs-sidebar__link";
 	if (isExternal) return /* @__PURE__ */ jsxs("a", {
 		className,
@@ -247,9 +283,9 @@ function NavLink({ href, isExternal, isActive, isNearby = false, Link, children
 				strokeLinejoin: "round",
 				children: /* @__PURE__ */ jsx("path", { d: "M14 4h6v6M20 4l-8 8M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" })
 			}),
-			/* @__PURE__ */ jsx("span", {
+			/* @__PURE__ */ jsxs("span", {
 				className: "wave-docs-sr-only",
-				children: " (opens in a new tab)"
+				children: [" ", externalLink]
 			})
 		]
 	});

package/dist/react/youtube.d.ts

@@ -3,11 +3,32 @@ import { ReactNode } from "react";
 interface YouTubeProps {
   /** The 11-character video id, e.g. `dQw4w9WgXcQ`. */
   id?: string | undefined;
+  /**
+   * Seconds to start at, from the link's `t` or `start`.
+   *
+   * ⚠️ IT USED TO BE DROPPED, AND THE FACADE AUTOPLAYS. `https://youtu.be/x?t=754`
+   * is a link to one moment in a two-hour talk — most of why anyone deep-links a
+   * video at all — and it opened at zero and started playing there, leaving the
+   * reader to work out that the author had meant somewhere else.
+   */
+  start?: number | undefined;
+  /** Playlist the video was linked inside, from the link's `list`. */
+  list?: string | undefined;
   /**
    * Accessible name for the player. Markdown carries no video title, so the
    * fallback is generic — pass a real one where you have it.
    */
   title?: string | undefined;
+  /**
+   * The closed facade's control. Default `'Play video: {title}'`.
+   *
+   * `{title}` is replaced with {@link YouTubeProps.title}. A placeholder rather
+   * than concatenation because a translator has to be able to move the name
+   * within the sentence — several languages put it first.
+   */
+  playLabel?: string | undefined;
+  /** The open facade's control. Default `'Hide video: {title}'`. */
+  hideLabel?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -48,6 +69,6 @@ interface YouTubeProps {
  * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
  * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
  */
-declare function YouTube({ id, title, className }: YouTubeProps): ReactNode;
+declare function YouTube({ id, start, list, title, playLabel, hideLabel, className }: YouTubeProps): ReactNode;
 //#endregion
 export { YouTube, YouTubeProps };

package/dist/react/youtube.js

@@ -1,6 +1,24 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/youtube.tsx
+/**
+* The embed URL, with whatever the author's link carried.
+*
+* `URLSearchParams` rather than string concatenation: `list` comes out of a
+* document and goes into a URL, and building this by hand is how a crafted
+* "playlist id" adds parameters of its own. `start` is already a number.
+*/
+function embedUrl(id, start, list) {
+	const params = new URLSearchParams({
+		rel: "0",
+		autoplay: "1"
+	});
+	if (start !== void 0 && Number.isFinite(start) && start > 0) params.set("start", String(Math.floor(start)));
+	if (list !== void 0 && list !== "") params.set("list", list);
+	return `https://www.youtube-nocookie.com/embed/${id}?${params.toString()}`;
+}
 const DEFAULT_TITLE = "YouTube video player";
+const DEFAULT_PLAY_LABEL = "Play video: {title}";
+const DEFAULT_HIDE_LABEL = "Hide video: {title}";
 /**
 * Click-to-load YouTube embed, with **no client JavaScript at all**.
 *
@@ -39,7 +57,7 @@ const DEFAULT_TITLE = "YouTube video player";
 * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
 * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
 */
-function YouTube({ id, title, className }) {
+function YouTube({ id, start, list, title, playLabel, hideLabel, className }) {
 	if (!id) return null;
 	const safeId = encodeURIComponent(id);
 	const label = title?.trim() || DEFAULT_TITLE;
@@ -78,17 +96,17 @@ function YouTube({ id, title, className }) {
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-sr-only wave-docs-youtube__label-play",
-					children: `Play video: ${label}`
+					children: (playLabel ?? DEFAULT_PLAY_LABEL).replace("{title}", label)
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-youtube__label-hide",
-					children: `Hide video: ${label}`
+					children: (hideLabel ?? DEFAULT_HIDE_LABEL).replace("{title}", label)
 				})
 			]
 		}), /* @__PURE__ */ jsx("iframe", {
 			className: "wave-docs-youtube__frame",
 			loading: "lazy",
-			src: `https://www.youtube-nocookie.com/embed/${safeId}?rel=0&autoplay=1`,
+			src: embedUrl(safeId, start, list),
 			title: label,
 			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
 			allowFullScreen: true

package/dist/render.d.ts

@@ -1,5 +1,6 @@
 import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+import { RehypeCodeFrameOptions } from "./plugins/rehype-code-frame.js";
 import { resolveMarkdownLink } from "./plugins/remark-doc-links.js";
 import { PluggableList } from "unified";
 //#region src/render.d.ts
@@ -11,7 +12,7 @@ import { PluggableList } from "unified";
  * same object to the source walk and to the renderer. Nothing here re-applies
  * defaults, so the two cannot drift.
  */
-type DocsRendererConfig = Pick<ResolvedDocsConfig, 'basePath' | 'assertLinks'>;
+type DocsRendererConfig = Pick<ResolvedDocsConfig, 'basePath' | 'onBrokenLinks' | 'onBrokenAnchors' | 'externalRoutes'>;
 interface DocsRendererOptions {
   config: DocsRendererConfig;
   /**
@@ -115,6 +116,16 @@ interface DocsRendererOptions {
    * than a monochrome block of DSL.
    */
   excludeLangs?: readonly string[] | undefined;
+  /**
+   * Accessible names for the copy button, for a site that is not in English.
+   *
+   * ⚠️ `rehypeCodeFrame` HAS TAKEN A `copyLabel` SINCE IT WAS WRITTEN AND
+   * NOTHING EVER PASSED ONE. The plugin is private, so the option was
+   * unreachable from every entry point — the README said the label was
+   * configurable and it was not. Baked into the HTML at build time, so
+   * overriding it costs no client bytes.
+   */
+  codeLabels?: RehypeCodeFrameOptions | undefined;
 }
 /**
  * Renders {@link DocFile}s. Build one per process and reuse it.