@waveso/docs 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # @waveso/docs
 
+## 0.8.0
+
+### Minor Changes
+
+- 98f8041: **The sidebar tells a category from a page at a glance.** A folder on every
+  group, a page on every page.
+
+  Weight and a chevron were the only difference, and that is not enough to scan:
+  a `Reference` group sitting directly above an `Internals` page read as one
+  undifferentiated column, and a real tree interleaves the two a dozen times. A
+  silhouette is read before any word is.
+
+  Two inline SVG paths, in the same style as the disclosure chevron and the
+  external-link mark that were already there. The package still ships no icon
+  set and takes no icon dependency — a folder and a page are as generic as the
+  chevron beside them.
+
+  `icons={false}` on `DocsSidebar` turns them off, for a host whose own
+  navigation has a different vocabulary and does not want a second one.
+
+  ⚠️ AN EXTERNAL LINK'S MARK MOVED TO THE HEAD OF ITS ROW. It used to sit at the
+  far end, which cost twice: the leading slot had to be an empty box to stop the
+  column going ragged, and the trailing edge carried two unrelated meanings —
+  "opens elsewhere" on one row, "expands" on the next. Leading is what a row _is_;
+  trailing is what it _does_. With the mark moved, the only thing at the far end
+  of any row is a chevron, which is what makes a group legible from across the
+  column, and it leaves that edge free for a status dot or an overflow control
+  later. A browser test measures the alignment, because the claim is about a
+  column and a column is geometry.
+
+  The sr-only "(opens in a new tab)" did **not** move with it — the name is still
+  read as "GitHub, opens in a new tab" rather than the other way round.
+
+  ⚠️ AND `icons={false}` PUTS THE MARK BACK ON THE TRAILING EDGE. With no column
+  to lead, rendering nothing would leave a link that leaves your site looking
+  exactly like one that does not. Turning off a decorative column is not consent
+  to drop a warning.
+
+  The markers sit at `opacity: 0.4` and inherit their row's colour rather than
+  carrying a grey of their own, so the relationship holds at every weight — a
+  bold group title and a muted page title each get a marker a fixed step lighter
+  than themselves. Full strength on hover and on the current page.
+
+  New public class names: `.wave-docs-sidebar__icon` and
+  `.wave-docs-sidebar__label`. The label wrapper is the flex hook that lets a row
+  put a chevron at its far end, and it is present whether or not there is a
+  marker beside it.
+
+  ## Your own icons, by name
+
+  The three built-ins are defaults, not a set. Content names an icon; the host
+  maps the name to a component:
+
+  ```yaml
+  # content/internals.md
+  icon: wrench
+  ```
+
+  ```json
+  // content/reference/meta.json
+  { "title": "Reference", "icon": "book" }
+  ```
+
+  ```tsx
+  <docs.Layout icons={{ wrench: Wrench, book: Book }}>{children}</docs.Layout>
+  ```
+
+  Also on `DocsSidebar` and `DocsNav` for a hand-assembled shell.
+
+  ⚠️ A NAME, NEVER ART THIS PACKAGE SHIPS. Content is authored in YAML and JSON
+  and cannot carry a React element, and a docs package mounted inside someone
+  else's application must not stand its iconography next to theirs. The bundle
+  grows by a lookup, not by an icon set — and never will by one.
+
+  ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT. `docs.Layout` is a
+  Server Component and the tree it hands the map to is not, so React serialises a
+  _reference_ to each icon; a server component cannot be one. Icons imported from
+  a library already satisfy this. The same boundary `search` documents.
+
+  A name with no entry in the map falls back to the built-in marker for that
+  node's type — a typo in one file leaves a folder where a book should be, not a
+  hole in the column.
+
+### Patch Changes
+
+- 72ad371: The sidebar's disclosure chevron points at the group it belongs to.
+
+  `.wave-docs-sidebar__group-header` is `justify-content: space-between`, so the
+  chevron sits flush against the navigation's inline end with the label at the
+  other side of the row — and unrotated it aimed at the panel's border. Worse
+  than at nothing: a chevron at the _trailing_ edge of a row is the platform
+  idiom for "this takes you somewhere else", so it read as navigation on a
+  control that only opens a list in place. A collapsed group now points back at
+  its own label; an open one still points down at its children.
+
+  ⚠️ AND IT MIRRORS, WHICH A ROTATION DOES NOT DO ON ITS OWN. `rotate` is
+  physical — 180deg is left in every writing mode — while every other property
+  placing that row is logical. Under `dir="rtl"` the header mirrors, the chevron
+  moves to the inline start and the label lands to its right, so a single
+  unmirrored rotation would point it out of the panel on the other side: the same
+  defect, reflected.
+
+  ⚠️ THE MIRROR IS `[dir='rtl']`, NOT `:dir(rtl)`, AND THAT IS NOT A STYLE
+  PREFERENCE. Next compiles this stylesheet with lightningcss, which downlevels
+  `:dir(rtl)` into a hardcoded list of right-to-left _languages_ —
+  `:is(:lang(ae), :lang(ar), … :lang(yi))`. Direction is not language, and the
+  substitution is wrong in both directions: `<html dir="rtl" lang="en">` gets no
+  mirror, `lang="ar" dir="ltr"` gets one it never asked for. It is invisible from
+  inside this repo, because the tests inject the source text into a `<style>`
+  element where `:dir()` behaves perfectly — it was caught by measuring the built
+  site. The stylesheet now uses `:dir()` nowhere, and a test enforces that.
+
+## 0.7.1
+
+### Patch Changes
+
+- 43af6e9: The back-to-top link appears when there is something to go back to.
+
+  It sat at the foot of the table of contents on every page, including at the top
+  of one, offering to return a reader to where they already were. It now fades in
+  between 25dvh and 35dvh of scroll and fades back out on the way up.
+
+  No JavaScript was added to do it. The reveal is a scroll-driven animation, so
+  scroll position alone drives it — no listener, no state, no re-render per
+  frame, and correct before the component has hydrated. `DocsToc` is the smallest
+  client component this package ships and it has not grown by a byte.
+
+  `visibility` moves with the fade, so the link leaves the tab order while it is
+  invisible rather than sitting there as a focus target nobody can see — and it
+  rejoins only once it is legible, not at the first pixel of the fade.
+
+  Where the timeline cannot run the link is simply always present, exactly as it
+  was: Firefox has not shipped scroll-driven animations, a page too short to
+  scroll leaves the timeline inactive, and so does a host that scrolls an inner
+  pane rather than the document. Nothing hides a control on the strength of a
+  feature the engine did not run.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -69,16 +69,16 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | At most |
 | --- | --- |
-| Everything the quick start ships, gzipped | 13.9 KB |
+| Everything the quick start ships, gzipped | 14 KB |
 | Search dialog and router wiring | 9.3 KB |
-| Navigation: one sidebar, open and closed | 2.9 KB |
+| Navigation: one sidebar, open and closed | 3 KB |
 | Table of contents | 0.9 KB |
 | Copy-button runtime | 1.1 KB |
 | hast over the wire vs HTML, prose page | 1.20× |
 | hast over the wire vs HTML, code and tables | 1.12× |
 | Highlighting vs no highlighting | 2.00× |
 
-The first row is the honest total: a reader who lands on a page of your documentation downloads under 13.9 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
+The first row is the honest total: a reader who lands on a page of your documentation downloads under 14 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
 
 The one real cost is the middle pair: shipping a tree instead of a string is about 20% more brotli on a prose page, and about 12% on a page with code and tables, where Shiki's token spans dominate both representations equally. That is the price of never handing markup to `dangerouslySetInnerHTML`, and it is the first number a skeptical reviewer should ask for.
 
@@ -202,7 +202,7 @@ Every component takes data as props, and every module that imports from `next/*`
 | --- | --- | --- |
 | `DocContent` | `react/doc-content` | Renders a hast tree, inside `.wave-docs-prose`. Server Component |
 | `DocsHero` | `react/hero` | A landing page's header. `title`, `description`, `actions`, `Link`, `externalLabel`. Server Component |
-| `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
+| `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation`. `icons` controls the marker column — see [Sidebar icons](#sidebar-icons) |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
 | `DocsLink` | `react/next-link` | `next/link`, adapted — pass it as `Link` when composing by hand |
@@ -212,7 +212,49 @@ Every component takes data as props, and every module that imports from `next/*`
 | `SkipLink` | `react/skip-link` | Targets `docs.Page`'s `<main>`; `DOCS_CONTENT_ID` is that id. `docs.Layout` renders one |
 | `createMarkdownComponents` | `react/markdown-components` | The element → component map. `defaultMarkdownComponents` is the unwired one |
 
-`DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end.
+`DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end — it fades in once the reader is about a third of a screen down and fades out again on the way back, on a scroll timeline rather than a scroll listener, so the component ships no extra bytes to do it. Where that timeline cannot run — an engine without scroll-driven animations, a page too short to scroll, or a host that scrolls an inner pane rather than the document — the link is simply always there.
+
+### Sidebar icons
+
+Every row in the sidebar carries a marker at its head: a folder on a group, a page on a page, an arrow on a link that leaves your site. Weight and a chevron were the only difference before, and where categories and pages interleave that is not enough to scan.
+
+Three glyphs ship. **No icon set does**, and none ever will — this package is mounted inside applications that already have one, and a second vocabulary beside theirs is worse than none. Your own icons come in by name:
+
+```yaml
+# content/reference/index.md
+---
+title: Reference
+icon: book
+---
+```
+
+```json
+// content/reference/meta.json — for a directory with no index page,
+// and for hand-written links
+{ "title": "Reference", "icon": "book", "pages": [{ "title": "npm", "href": "https://npmjs.com", "icon": "package" }] }
+```
+
+```tsx
+import { DocsSidebar } from '@waveso/docs/react/sidebar';
+import type { DocNavNode } from '@waveso/docs/types';
+
+// Yours: `lucide-react`, your design system, or hand-written. Rendered with no
+// props, in a 1rem box — `currentColor` and `100%` keep it in line with the
+// built-ins and with the row it sits on.
+const Book = () => (
+  <svg viewBox="0 0 24 24" width="100%" height="100%" fill="none" stroke="currentColor">
+    <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20V2H6.5A2.5 2.5 0 0 0 4 4.5v15Z" />
+  </svg>
+);
+
+export function Nav({ nav, pathname }: { nav: DocNavNode[]; pathname: string }) {
+  return <DocsSidebar nav={nav} pathname={pathname} icons={{ book: Book }} />;
+}
+```
+
+A name with no entry in the map falls back to the built-in marker for that node's type — a typo in one file leaves a folder where a book should be, not a hole in the column. The component is rendered with no props, in a `1rem` box, and the built-ins use `currentColor`, so anything following those two conventions sits in line with them.
+
+`icons={false}` removes the column entirely. The external-link mark moves back to the trailing edge there: turning off a decorative column is not consent to drop a warning that a link leaves your site.
 
 The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` carries `src`, `alt`, `width` and `height` — the four `next/image` refuses to render without — and adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to it; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
 

package/dist/frontmatter.d.ts

@@ -32,6 +32,7 @@ declare const docFrontmatterSchema: z.ZodObject<{
   draft: z.ZodExactOptional<z.ZodBoolean>;
   aliases: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
   order: z.ZodExactOptional<z.ZodNumber>;
+  icon: z.ZodExactOptional<z.ZodString>;
   actions: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     href: z.ZodString;

package/dist/frontmatter.js

@@ -32,6 +32,7 @@ const docFrontmatterSchema = z.object({
 	draft: z.boolean().exactOptional(),
 	aliases: z.array(z.string()).exactOptional(),
 	order: z.number().exactOptional(),
+	icon: z.string().min(1).exactOptional(),
 	actions: z.array(z.object({
 		label: z.string().min(1),
 		href: z.string().min(1).refine(isSafeHref, "must be a safe URL (no javascript: or data:)"),

package/dist/meta.d.ts

@@ -10,9 +10,11 @@ import { z } from "zod";
  */
 declare const docsMetaSchema: z.ZodObject<{
   title: z.ZodExactOptional<z.ZodString>;
+  icon: z.ZodExactOptional<z.ZodString>;
   pages: z.ZodExactOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     title: z.ZodString;
     href: z.ZodString;
+    icon: z.ZodExactOptional<z.ZodString>;
   }, z.core.$strict>]>>>;
 }, z.core.$strict>;
 /**

package/dist/meta.js

@@ -25,9 +25,11 @@ const REST = "...";
 */
 const docsMetaSchema = z.strictObject({
 	title: z.string().exactOptional(),
+	icon: z.string().min(1).exactOptional(),
 	pages: z.array(z.union([z.string(), z.strictObject({
 		title: z.string(),
-		href: z.string().refine(isSafeHref, { message: "that is not a scheme this package will put in a link. Use http(s), mailto, tel, sms, ftp, irc, xmpp, news, feed, git or matrix — or a path, which needs no scheme at all." })
+		href: z.string().refine(isSafeHref, { message: "that is not a scheme this package will put in a link. Use http(s), mailto, tel, sms, ftp, irc, xmpp, news, feed, git or matrix — or a path, which needs no scheme at all." }),
+		icon: z.string().min(1).exactOptional()
 	})])).exactOptional()
 });
 /**
@@ -93,7 +95,8 @@ function orderNavEntries(entries, meta, metaPath, depth) {
 				type: "link",
 				title: page.title,
 				href: page.href,
-				external: opensInNewTab(page.href)
+				external: opensInNewTab(page.href),
+				...page.icon !== void 0 ? { icon: page.icon } : {}
 			});
 			continue;
 		}

package/dist/next.d.ts

@@ -3,6 +3,7 @@ import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.
 import { SerializableSearchOptions } from "./search-options.js";
 import { DocsLabels } from "./react/shell-labels.js";
 import { MarkdownComponents } from "./react/markdown-components.js";
+import { DocsIconMap } from "./react/sidebar.js";
 import { DocsLayoutSearchProps } from "./react/layout.js";
 import { DocsSource } from "./source.js";
 import { ReactNode } from "react";
@@ -154,6 +155,19 @@ interface DocsLayoutProps {
    * mean naming one string cost you the other twenty-one.
    */
   labels?: DocsLabels | undefined;
+  /**
+   * The sidebar's marker column: `true` (default), `false`, or your own icons
+   * keyed by the `icon` names your content authors in frontmatter and
+   * `meta.json`. See `DocsSidebarProps.icons`.
+   *
+   * ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT — the same
+   * boundary `search` documents at length. This is a Server Component handing
+   * props to a Client one, so React serialises a *reference* to a client
+   * component and cannot serialise a server one. Icons imported from a library
+   * already satisfy this; one defined inline in a server file fails the build
+   * at the boundary.
+   */
+  icons?: boolean | DocsIconMap | undefined;
 }
 /** Props Next hands a page in the App Router. */
 interface DocsPageProps {

package/dist/next.js

@@ -468,7 +468,7 @@ function createDocsRoute(options) {
 		async IndexPage() {
 			return renderRoute([]);
 		},
-		async Layout({ children, search, labels }) {
+		async Layout({ children, search, labels, icons }) {
 			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;
@@ -485,7 +485,8 @@ function createDocsRoute(options) {
 				nav: await requestScopedSource.nav(),
 				searchIndexUrl,
 				search: searchProps,
-				...shellLabels === void 0 ? {} : { labels: shellLabels }
+				...shellLabels === void 0 ? {} : { labels: shellLabels },
+				...icons === void 0 ? {} : { icons }
 			});
 		},
 		async generateStaticParams() {

package/dist/react/layout.d.ts

@@ -2,6 +2,7 @@ import { DocNavNode } from "../types.js";
 import { SerializableSearchOptions } from "../search-options.js";
 import { DocsLabels } from "./shell-labels.js";
 import { DocsSearchProps } from "./next-search.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/layout.d.ts
 /**
@@ -53,7 +54,21 @@ interface DocsLayoutShellProps {
    * passed either. Configuration that could not be configured.
    */
   labels?: DocsLabels | undefined;
+  /**
+   * The sidebar's marker column: `true` (default), `false`, or your own icons
+   * keyed by the `icon` names your content authors. See
+   * {@link DocsSidebarProps.icons}.
+   *
+   * ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT. This shell is a
+   * Server Component and the tree it hands them to is not, so the map crosses
+   * that boundary — React can serialise a *reference* to a client component and
+   * cannot serialise a server one. Import your icons from a module carrying
+   * `'use client'` (every icon library does) and this is invisible; define one
+   * inline in a server file and the build fails at the boundary rather than
+   * here.
+   */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsLayoutShell({ children, nav, searchIndexUrl, search, labels }: DocsLayoutShellProps): ReactNode;
+declare function DocsLayoutShell({ children, nav, searchIndexUrl, search, labels, icons }: DocsLayoutShellProps): ReactNode;
 //#endregion
 export { DocsLayoutSearchProps, DocsLayoutShell, DocsLayoutShellProps };

package/dist/react/layout.js

@@ -4,7 +4,7 @@ import { DocsNextNav } from "./next-nav.js";
 import { SkipLink } from "./skip-link.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/layout.tsx
-function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels }) {
+function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels, icons }) {
 	const text = resolveLabels(labels);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(SkipLink, { children: text.skipToContent }), /* @__PURE__ */ jsx("div", {
 		className: "wave-docs-shell",
@@ -18,6 +18,7 @@ function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels
 				...labels?.expandGroup === void 0 ? {} : { expandGroup: labels.expandGroup },
 				...labels?.collapseGroup === void 0 ? {} : { collapseGroup: labels.collapseGroup },
 				...labels?.externalLink === void 0 ? {} : { externalLink: labels.externalLink },
+				...icons === void 0 ? {} : { icons },
 				children: search === false ? null : /* @__PURE__ */ jsx(DocsSearch, {
 					indexUrl: searchIndexUrl,
 					...search === true ? {} : search,

package/dist/react/nav.d.ts

@@ -1,5 +1,6 @@
 import { DocNavNode } from "../types.js";
 import { DocsLinkComponent } from "./markdown-components.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/nav.d.ts
 /** The navigation's `id`, and the trigger's `aria-controls`. */
@@ -26,7 +27,9 @@ interface DocsNavProps {
   expandGroup?: string | undefined;
   collapseGroup?: string | undefined;
   externalLink?: string | undefined;
+  /** The marker column. See `DocsSidebarProps.icons`. */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsNav({ nav, pathname, Link, label, children, closeLabel, openLabel, expandGroup, collapseGroup, externalLink }: DocsNavProps): ReactNode;
+declare function DocsNav({ nav, pathname, Link, label, children, closeLabel, openLabel, expandGroup, collapseGroup, externalLink, icons }: DocsNavProps): ReactNode;
 //#endregion
 export { DOCS_NAV_ID, DocsNav, DocsNavProps };

package/dist/react/nav.js

@@ -5,7 +5,7 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/nav.tsx
 /** The navigation's `id`, and the trigger's `aria-controls`. */
 const DOCS_NAV_ID = "wave-docs-nav";
-function DocsNav({ nav, pathname, Link, label = "Documentation", children, closeLabel = "Close navigation", openLabel = "Open navigation", expandGroup, collapseGroup, externalLink }) {
+function DocsNav({ nav, pathname, Link, label = "Documentation", children, closeLabel = "Close navigation", openLabel = "Open navigation", expandGroup, collapseGroup, externalLink, icons }) {
 	const shellRef = useRef(null);
 	const navRef = useRef(null);
 	const returnFocusRef = useRef(null);
@@ -98,7 +98,8 @@ function DocsNav({ nav, pathname, Link, label = "Documentation", children, close
 				Link,
 				...expandGroup === void 0 ? {} : { expandGroup },
 				...collapseGroup === void 0 ? {} : { collapseGroup },
-				...externalLink === void 0 ? {} : { externalLink }
+				...externalLink === void 0 ? {} : { externalLink },
+				...icons === void 0 ? {} : { icons }
 			})]
 		}), /* @__PURE__ */ jsx("button", {
 			type: "button",

package/dist/react/next-nav.d.ts

@@ -1,4 +1,5 @@
 import { DocNavNode } from "../types.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/next-nav.d.ts
 interface DocsNextNavProps {
@@ -13,7 +14,9 @@ interface DocsNextNavProps {
   expandGroup?: string | undefined;
   collapseGroup?: string | undefined;
   externalLink?: string | undefined;
+  /** The marker column. See `DocsSidebarProps.icons`. */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }: DocsNextNavProps): ReactNode;
+declare function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink, icons }: DocsNextNavProps): ReactNode;
 //#endregion
 export { DocsNextNav, DocsNextNavProps };

package/dist/react/next-nav.js

@@ -19,7 +19,7 @@ import { usePathname } from "next/navigation";
 */
 /** Module scope: a fresh identity here remounts every nav link on every render. */
 const Link = wrapNextLink(NextLink);
-function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }) {
+function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink, icons }) {
 	return /* @__PURE__ */ jsx(DocsNav, {
 		nav,
 		pathname: usePathname(),
@@ -30,6 +30,7 @@ function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup,
 		...expandGroup === void 0 ? {} : { expandGroup },
 		...collapseGroup === void 0 ? {} : { collapseGroup },
 		...externalLink === void 0 ? {} : { externalLink },
+		...icons === void 0 ? {} : { icons },
 		children
 	});
 }

package/dist/react/sidebar.d.ts

@@ -1,7 +1,17 @@
 import { DocNavNode } from "../types.js";
 import { DocsLinkComponent } from "./markdown-components.js";
-import { ReactNode } from "react";
+import { ComponentType, ReactNode } from "react";
 //#region src/react/sidebar.d.ts
+/**
+ * `icon` names to components, for `DocsSidebar`'s `icons` prop.
+ *
+ * The component is rendered with no props: an icon that needs configuration is
+ * a closure the host writes, not a contract this package invents. It should
+ * draw at the size it is given — the column is `1rem` square and the built-in
+ * markers use `currentColor`, so anything following those two conventions sits
+ * in line with them.
+ */
+type DocsIconMap = Record<string, ComponentType>;
 interface DocsSidebarProps {
   /** The tree from `@waveso/docs/source`. */
   nav: DocNavNode[];
@@ -32,6 +42,44 @@ interface DocsSidebarProps {
    * The separating space is markup, so this is the sentence and nothing else.
    */
   externalLink?: string | undefined;
+  /**
+   * The marker column. `true` (default), `false`, or your own icons.
+   *
+   * Weight and a chevron were the only things separating a category from a
+   * page, and in a tree where the two interleave — a `Reference` group sitting
+   * directly above an `Internals` page — that is not enough to scan. A leading
+   * glyph gives the column a shape you read before you read any words.
+   *
+   * `false` renders no markers at all, for a host whose own navigation has a
+   * different vocabulary and does not want a second one. The external-link mark
+   * returns to the trailing edge there — turning off a decorative column is not
+   * consent to drop a warning.
+   *
+   * A **map** replaces the defaults with your components, keyed by the `icon`
+   * name authored in frontmatter or `meta.json`:
+   *
+   * ```tsx
+   * import { Book, Rocket } from 'lucide-react';
+   *
+   * <DocsSidebar nav={nav} pathname={pathname}
+   *   icons={{ book: Book, rocket: Rocket }} />
+   * ```
+   *
+   * ```yaml
+   * # content/reference/index.md
+   * icon: book
+   * ```
+   *
+   * ⚠️ A NAME THE HOST RESOLVES, NEVER ART THIS PACKAGE SHIPS. Content is
+   * authored in YAML and JSON and cannot carry a React element, and a docs
+   * package mounted inside someone else's application must not put its
+   * iconography beside theirs. Three markers ship; everything else is yours.
+   *
+   * A name with no entry in the map falls back to the built-in marker for that
+   * node's type. A typo in one file leaves a folder where a book should be —
+   * not a hole in the column.
+   */
+  icons?: boolean | DocsIconMap | undefined;
   className?: string | undefined;
 }
 /**
@@ -76,6 +124,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, expandGroup, collapseGroup, externalLink, className }: DocsSidebarProps): ReactNode;
+declare function DocsSidebar({ nav, pathname, Link, label, expandGroup, collapseGroup, externalLink, icons, className }: DocsSidebarProps): ReactNode;
 //#endregion
-export { DocsSidebar, DocsSidebarProps };
+export { DocsIconMap, DocsSidebar, DocsSidebarProps };

package/dist/react/sidebar.js

@@ -66,7 +66,8 @@ 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", expandGroup, collapseGroup, externalLink, className }) {
+function DocsSidebar({ nav, pathname, Link, label = "Docs", expandGroup, collapseGroup, externalLink, icons = true, className }) {
+	const iconMap = icons === false ? false : icons === true ? {} : icons;
 	const text = {
 		expandGroup: expandGroup ?? DEFAULT_SIDEBAR_LABELS.expandGroup,
 		collapseGroup: collapseGroup ?? DEFAULT_SIDEBAR_LABELS.collapseGroup,
@@ -108,6 +109,7 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", expandGroup, collaps
 			nodes: nav,
 			depth: 0,
 			keyPrefix: baseId,
+			icons: iconMap,
 			pathname,
 			Link,
 			toggled,
@@ -157,7 +159,7 @@ function scrollableAncestor(element) {
 	}
 	return null;
 }
-function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, text, id }) {
+function NavList({ nodes, depth, keyPrefix, icons, 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,
@@ -175,31 +177,47 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, t
 				}, key);
 				case "link": return /* @__PURE__ */ jsx("li", {
 					className: "wave-docs-sidebar__item",
-					children: /* @__PURE__ */ jsx(NavLink, {
+					children: /* @__PURE__ */ jsxs(NavLink, {
 						href: node.href,
 						isExternal: node.external,
 						isActive: !node.external && isActiveHref(pathname, node.href),
 						isNearby: holdsActive,
 						Link,
 						externalLink: text.externalLink,
-						children: node.title
+						icons,
+						children: [icons === false ? null : /* @__PURE__ */ jsx(NavIcon, {
+							type: "external",
+							name: node.icon,
+							icons
+						}), /* @__PURE__ */ jsx("span", {
+							className: "wave-docs-sidebar__label",
+							children: node.title
+						})]
 					})
 				}, key);
 				case "page": return /* @__PURE__ */ jsx("li", {
 					className: "wave-docs-sidebar__item",
-					children: /* @__PURE__ */ jsx(NavLink, {
+					children: /* @__PURE__ */ jsxs(NavLink, {
 						href: node.href,
 						isExternal: false,
 						isActive: isActiveHref(pathname, node.href),
 						isNearby: holdsActive,
 						Link,
-						children: node.title
+						children: [icons === false ? null : /* @__PURE__ */ jsx(NavIcon, {
+							type: "file",
+							name: node.icon,
+							icons
+						}), /* @__PURE__ */ jsx("span", {
+							className: "wave-docs-sidebar__label",
+							children: node.title
+						})]
 					})
 				}, key);
 				case "group": return /* @__PURE__ */ jsx(NavGroup, {
 					node,
 					itemKey: key,
 					depth,
+					icons,
 					pathname,
 					Link,
 					toggled,
@@ -211,7 +229,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, t
 		})
 	});
 }
-function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, text }) {
+function NavGroup({ node, itemKey, depth, icons, pathname, Link, toggled, onToggle, text }) {
 	const listId = `${itemKey}-list`;
 	const hasActive = containsActive(node, pathname);
 	const isOpen = toggled[itemKey] ?? hasActive;
@@ -227,17 +245,32 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, tex
 				"aria-expanded": isOpen,
 				"aria-controls": isOpen ? listId : void 0,
 				onClick: () => onToggle(itemKey, !isOpen),
-				children: [/* @__PURE__ */ jsx("span", {
-					className: "wave-docs-sidebar__group-title",
-					children: node.title
-				}), /* @__PURE__ */ jsx(Chevron, { isOpen })]
-			}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(NavLink, {
+				children: [
+					icons === false ? null : /* @__PURE__ */ jsx(NavIcon, {
+						type: "folder",
+						name: node.icon,
+						icons
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "wave-docs-sidebar__group-title",
+						children: node.title
+					}),
+					/* @__PURE__ */ jsx(Chevron, { isOpen })
+				]
+			}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(NavLink, {
 				href: node.href,
 				isExternal: false,
 				isActive: isGroupActive,
 				isNearby: hasActive,
 				Link,
-				children: node.title
+				children: [icons === false ? null : /* @__PURE__ */ jsx(NavIcon, {
+					type: "folder",
+					name: node.icon,
+					icons
+				}), /* @__PURE__ */ jsx("span", {
+					className: "wave-docs-sidebar__label",
+					children: node.title
+				})]
 			}), /* @__PURE__ */ jsx("button", {
 				type: "button",
 				className: "wave-docs-sidebar__group-toggle",
@@ -252,6 +285,7 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, tex
 			nodes: node.children,
 			depth: depth + 1,
 			keyPrefix: itemKey,
+			icons,
 			pathname,
 			Link,
 			toggled,
@@ -260,7 +294,7 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, tex
 		}) : null]
 	});
 }
-function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalLink = DEFAULT_SIDEBAR_LABELS.externalLink, children }) {
+function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalLink = DEFAULT_SIDEBAR_LABELS.externalLink, icons = {}, children }) {
 	const className = "wave-docs-sidebar__link";
 	if (isExternal) return /* @__PURE__ */ jsxs("a", {
 		className,
@@ -269,7 +303,7 @@ function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalL
 		rel: "noopener noreferrer",
 		children: [
 			children,
-			/* @__PURE__ */ jsx("svg", {
+			icons === false ? /* @__PURE__ */ jsx("svg", {
 				className: "wave-docs-sidebar__external",
 				"aria-hidden": "true",
 				focusable: "false",
@@ -281,8 +315,8 @@ function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalL
 				strokeWidth: "2",
 				strokeLinecap: "round",
 				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" })
-			}),
+				children: /* @__PURE__ */ jsx("path", { d: NAV_ICON_PATHS.external[0] })
+			}) : null,
 			/* @__PURE__ */ jsxs("span", {
 				className: "wave-docs-sr-only",
 				children: [" ", externalLink]
@@ -303,6 +337,58 @@ function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalL
 		children
 	});
 }
+/**
+* The glyph at the head of a row: a folder for a group, a page for a page.
+*
+* Weight and a chevron were the only things telling a category from a page, and
+* where the two interleave — a `Reference` group directly above an `Internals`
+* page — that is not enough to scan a column of twenty. A silhouette is read
+* before any word is.
+*
+* An external link takes the third glyph, in the same leading slot. It used to
+* carry that mark at the *far* end of its row, which cost twice: the leading
+* slot then had to be an empty box to keep the column from going ragged, and
+* the trailing edge held two unrelated meanings — "opens elsewhere" on one row,
+* "expands" on the next. Leading is what a row *is*; trailing is what it
+* *does*. With the mark moved, the only thing at the far end of any row is a
+* chevron, which is what makes a group legible from across the column — and
+* leaves that edge free for a status dot or an overflow control later.
+*
+* ⚠️ THE VISUAL MARK MOVED AND THE ANNOUNCED ONE DID NOT. The sr-only "(opens
+* in a new tab)" stays after the link text, so the name is still read as
+* "GitHub, opens in a new tab" rather than the other way round.
+*
+* Inline SVG, matching `Chevron` and the external mark rather than a font or a
+* dependency — the package ships no icon set, and these two are as generic as
+* the chevron beside them.
+*/
+const NAV_ICON_PATHS = {
+	folder: ["M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"],
+	file: ["M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z", "M14 2v4a2 2 0 0 0 2 2h4"],
+	external: ["M14 4h6v6M20 4l-8 8M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5"]
+};
+function NavIcon({ type, name, icons }) {
+	const Custom = name === void 0 ? void 0 : icons[name];
+	if (Custom !== void 0) return /* @__PURE__ */ jsx("span", {
+		className: "wave-docs-sidebar__icon",
+		"aria-hidden": "true",
+		children: /* @__PURE__ */ jsx(Custom, {})
+	});
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-sidebar__icon",
+		"aria-hidden": "true",
+		focusable: "false",
+		viewBox: "0 0 24 24",
+		width: "16",
+		height: "16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: NAV_ICON_PATHS[type].map((d) => /* @__PURE__ */ jsx("path", { d }, d))
+	});
+}
 function Chevron({ isOpen }) {
 	return /* @__PURE__ */ jsx("svg", {
 		className: "wave-docs-sidebar__chevron",

package/dist/source.js

@@ -381,17 +381,20 @@ function buildNav(dir, config) {
 		const visible = index && isVisibleIn(index.doc, config) ? index : void 0;
 		const title = groupTitle(child, visible?.doc);
 		const href = visible?.doc.href;
+		const icon = child.meta?.icon ?? visible?.doc.frontmatter.icon;
 		const group = {
 			type: "group",
 			title,
 			children,
-			...href !== void 0 ? { href } : {}
+			...href !== void 0 ? { href } : {},
+			...icon !== void 0 ? { icon } : {}
 		};
 		const node = children.length === 0 && visible !== void 0 && href !== void 0 ? {
 			type: "page",
 			title,
 			href,
-			slug: visible.doc.slug
+			slug: visible.doc.slug,
+			...icon !== void 0 ? { icon } : {}
 		} : group;
 		const order = visible?.doc.frontmatter.order;
 		entries.push({
@@ -403,7 +406,8 @@ function buildNav(dir, config) {
 				type: "page",
 				title: navTitle(visible.doc),
 				href,
-				slug: visible.doc.slug
+				slug: visible.doc.slug,
+				...visible.doc.frontmatter.icon !== void 0 ? { icon: visible.doc.frontmatter.icon } : {}
 			} } : {},
 			...order !== void 0 ? { order } : {}
 		});
@@ -420,7 +424,8 @@ function toPageEntry(page, config) {
 			type: "page",
 			title,
 			href: page.doc.href,
-			slug: page.doc.slug
+			slug: page.doc.slug,
+			...page.doc.frontmatter.icon !== void 0 ? { icon: page.doc.frontmatter.icon } : {}
 		},
 		...order !== void 0 ? { order } : {},
 		...isVisibleIn(page.doc, config) ? {} : { hidden: true }

package/dist/styles.css

@@ -1575,6 +1575,71 @@
     font-weight: 600;
   }
 
+  /*
+   * The row is `justify-content: space-between`, so the label has to claim the
+   * space or the icon and the text end up at opposite edges with a hole between
+   * them. `min-width: 0` because a long title in a 240px column must be allowed
+   * to shrink; without it the flex base is the text's min-content width and the
+   * row overflows instead of wrapping.
+   */
+  .wave-docs-sidebar__label,
+  .wave-docs-sidebar__group-title {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  /*
+   * The type marker: a folder on a group, a page on a page.
+   *
+   * ⚠️ THE BOX IS DECLARED HERE, NOT LEFT TO THE SVG'S OWN WIDTH, because one
+   * of these has no SVG in it. An external link carries its mark at the far end
+   * of the row and needs no second one, so it gets an empty box — and an empty
+   * `<span>` with no size is a column where three labels start 24px left of
+   * every other label. Ragged is the defect this feature exists to remove.
+   */
+  .wave-docs-sidebar__icon {
+    flex: none;
+    inline-size: 1rem;
+    block-size: 1rem;
+    /*
+     * ⚠️ `inherit` AND `opacity`, NOT A COLOUR OF ITS OWN. A fixed grey put a
+     * bold group title next to a marker several steps lighter than it and a
+     * muted page title next to one barely lighter, so the column read as two
+     * different treatments. Fading whatever the row already is keeps one
+     * relationship at every weight — and it is the reason the active row's
+     * marker turns accent-blue with its label rather than staying grey.
+     */
+    color: inherit;
+    opacity: 0.4;
+  }
+
+  /*
+   * A host's own icon, in the column's box.
+   *
+   * `grid` rather than `block`: the component inside is theirs and may be any
+   * size, and a grid with `place-items: center` centres it in our 1rem square
+   * without needing it to fill one. `> *` caps it at the box so an icon
+   * authored at 24 does not push the row taller than every other row.
+   */
+  span.wave-docs-sidebar__icon {
+    display: grid;
+    place-items: center;
+  }
+
+  .wave-docs-sidebar__icon > * {
+    max-inline-size: 100%;
+    max-block-size: 100%;
+  }
+
+  /* Full strength the moment the row is the reader's own or under their
+   * pointer. A current page whose marker stayed faded reads as
+   * half-highlighted. */
+  .wave-docs-sidebar__link:hover .wave-docs-sidebar__icon,
+  .wave-docs-sidebar__group-button:hover .wave-docs-sidebar__icon,
+  .wave-docs-sidebar__link[aria-current='page'] .wave-docs-sidebar__icon {
+    opacity: 1;
+  }
+
   .wave-docs-sidebar__list:not([data-depth='0']) {
     margin-inline-start: 0.5rem;
     padding-inline-start: 0.5rem;
@@ -1646,11 +1711,55 @@
     color: var(--wave-docs-fg);
   }
 
+  /*
+   * The chevron points at the label it belongs to, not away from it.
+   *
+   * `.wave-docs-sidebar__group-header` is `justify-content: space-between`, so
+   * this sits flush against the navigation's inline end with the label at the
+   * other side of the row. The icon is Lucide's `chevron-right`, and unrotated
+   * it therefore aimed at the panel's border — at nothing. Worse than nothing,
+   * in fact: a chevron at the *trailing* edge of a row is the platform idiom
+   * for "this takes you somewhere else", so it read as navigation on a control
+   * that only opens a list in place.
+   *
+   * ⚠️ AND THAT IS WHY THERE IS A MIRROR RULE. `rotate` is physical — `180deg`
+   * is left in every writing mode — while everything else positioning this row
+   * is logical, so the header mirrors under `dir="rtl"` and a lone physical
+   * rotation does not. Mirrored, the chevron moves to the inline start with the
+   * label to its right, and 180deg would then point it out of the panel on the
+   * other side. `0deg` is what "at the label" means there.
+   *
+   * ⚠️ `[dir='rtl']`, AND NOT `:dir(rtl)`, WHICH IS THE SELECTOR FOR THIS JOB
+   * AND DOES NOT SURVIVE THE BUILD. Next compiles this sheet with lightningcss,
+   * which downlevels `:dir(rtl)` into a hardcoded list of right-to-left
+   * *languages*:
+   *
+   *   .wave-docs-sidebar__chevron:is(:lang(ae), :lang(ar), … :lang(yi))
+   *
+   * Direction is not language. Measured on the site with `<html dir="rtl"
+   * lang="en">`: `:dir(rtl)` matched the element, the rule was nowhere in the
+   * served stylesheet, and the chevron kept pointing out of the panel. It fails
+   * the other way too — `lang="ar" dir="ltr"` gets the mirror it did not ask
+   * for. The attribute selector is plain CSS 2.1, so no pipeline has an opinion
+   * about it, and it is what `rtl:` compiles to in every design system that
+   * ships one.
+   */
   .wave-docs-sidebar__chevron {
     flex: none;
     color: var(--wave-docs-fg-subtle);
+    rotate: 180deg;
   }
 
+  [dir='rtl'] .wave-docs-sidebar__chevron {
+    rotate: 0deg;
+  }
+
+  /*
+   * Open is down in both directions, so this needs no mirror — and it must
+   * come last, because the mirror above matches with the same specificity
+   * (0,2,0 either way) and would otherwise hold a mirrored open group pointing
+   * sideways.
+   */
   .wave-docs-sidebar__chevron[data-open] {
     rotate: 90deg;
   }
@@ -1673,6 +1782,35 @@
     .wave-docs-sidebar__chevron {
       transition: rotate 150ms ease-out;
     }
+
+    /*
+     * The row and its marker ease together, and the row is half of it.
+     *
+     * ⚠️ THE LINKS HAD NO TRANSITION AT ALL — the TOC's did, which is why this
+     * looked like an oversight only in the sidebar. Fading the marker alone
+     * would have been worse than fading nothing: the glyph would drift up to
+     * full strength while the surface under it snapped, so the two halves of
+     * one hover would visibly disagree.
+     *
+     * `background-color`, not `background`: the shorthand includes
+     * `background-image`, and naming it here would put this rule in the way of
+     * any consumer who paints one.
+     */
+    .wave-docs-sidebar__link,
+    .wave-docs-sidebar__group-button,
+    .wave-docs-sidebar__group-toggle {
+      transition:
+        background-color 150ms ease-out,
+        color 150ms ease-out;
+    }
+
+    /* `color` as well as `opacity`: the marker inherits its row's colour, and
+     * on the current page that is a jump from muted grey to accent blue. */
+    .wave-docs-sidebar__icon {
+      transition:
+        opacity 150ms ease-out,
+        color 150ms ease-out;
+    }
   }
 }
 
@@ -1725,6 +1863,89 @@
     color: var(--wave-docs-fg);
   }
 
+  /*
+   * ⚠️ IT ONLY APPEARS ONCE THERE IS SOMETHING TO GO BACK TO, AND NOTHING IN
+   * JAVASCRIPT DECIDES THAT.
+   *
+   * A scroll-driven animation, so scroll position alone drives it: no listener,
+   * no state, no re-render on every frame of a scroll, and it is right before
+   * hydration rather than after it. `toc` is the smallest client component this
+   * package ships — 900 bytes, and its budget note exists to keep it that way —
+   * so the alternative was to grow the one bundle that should never grow, in
+   * order to recompute a number the compositor already has.
+   *
+   * ⚠️ `root`, NOT `nearest`. Above 80rem `.wave-docs-layout__toc` is itself a
+   * scroll container (`overflow-y: auto`, so a long column of headings scrolls
+   * in place), and `nearest` resolves to it. The animation would then track how
+   * far the reader had scrolled the *table of contents*, which on almost every
+   * page never scrolls at all — an inactive timeline, and a link that never
+   * appears. Same shape as the `nearest`/`self` trap on the table shadow above,
+   * arrived at from the opposite direction.
+   *
+   * ⚠️ AND THE RULE ABOVE IS THE FALLBACK, WHICH IS WHY NOTHING HERE OVERRIDES
+   * IT. Three cases collapse into one: Firefox does not match this `@supports`
+   * yet; a page too short to scroll leaves the timeline inactive; and so does a
+   * host that scrolls an inner pane rather than the document. In all three the
+   * link is simply always present, exactly as it was before this block existed.
+   * Nothing hides a control on the strength of a feature the engine did not run.
+   *
+   * `dvh` rather than `px`: the link is redundant while the top of the document
+   * is still on screen, and "still on screen" is a fraction of the viewport
+   * rather than a constant. On a 900px window it fades in between 225px and
+   * 315px of scroll. `dvh` because this sheet uses no `vh` anywhere, and the
+   * reason it does not — the retracted mobile URL bar — costs nothing here: the
+   * column this link lives in is `display: none` below 80rem.
+   *
+   * No `prefers-reduced-motion` gate, deliberately. That setting is about things
+   * that move under a reader who did not ask them to; this is opacity, and the
+   * reader's own scrolling is its clock.
+   */
+  @supports (animation-timeline: scroll()) {
+    .wave-docs-toc__top {
+      animation-timeline: scroll(root block);
+      animation-timing-function: linear;
+      animation-fill-mode: both;
+      animation-name: wave-docs-toc-top-reveal;
+      animation-range: 25dvh 35dvh;
+    }
+  }
+
+  /*
+   * ⚠️ `visibility` KEEPS A LINK NOBODY CAN SEE OUT OF THE TAB ORDER, AND THE
+   * MIDDLE FRAME IS WHAT DECIDES WHEN IT REJOINS.
+   *
+   * `opacity` alone leaves a fully focusable, fully clickable link sitting
+   * invisibly at the foot of the rail: Tab reaches it and the focus ring is
+   * drawn around nothing.
+   *
+   * `visibility` interpolates as a step with one exception — across an interval
+   * where *either* endpoint is `visible` it is `visible` the whole way. Two
+   * frames would therefore flip it one pixel past the threshold and hand the
+   * link back to the tab order at an opacity of almost zero, which is the same
+   * defect a frame later. Two adjacent `hidden` frames have no `visible`
+   * endpoint between them, the exception does not apply, and the step lands at
+   * 60% — where the link is legible.
+   *
+   * That middle frame sits exactly on the linear ramp, so it changes the fade
+   * by nothing at all. Being the second `hidden` is its whole job.
+   */
+  @keyframes wave-docs-toc-top-reveal {
+    0% {
+      opacity: 0;
+      visibility: hidden;
+    }
+
+    60% {
+      opacity: 0.6;
+      visibility: hidden;
+    }
+
+    100% {
+      opacity: 1;
+      visibility: visible;
+    }
+  }
+
   .wave-docs-sidebar__external {
     /* Baseline-ish against the label, and never a flex item that grows. */
     margin-inline-start: 0.25rem;

package/dist/types.d.ts

@@ -59,6 +59,20 @@ interface DocFrontmatter {
    * Lower sorts first; pages without an order sort last, alphabetically.
    */
   order?: number | undefined;
+  /**
+   * Sidebar marker for this page, as a name the *consumer* resolves.
+   *
+   * A name and not a component, because frontmatter is data: it is authored by
+   * whoever writes the page, in YAML, and cannot carry a React element. The
+   * host maps the name to their own icon via `DocsSidebar`'s `icons` prop, so
+   * the art belongs to whichever site is rendering — which is the only shape
+   * that serves a package mounted inside someone else's application.
+   *
+   * An unmapped name falls back to the default page marker rather than
+   * rendering nothing: a typo in one file should not knock a hole in the
+   * column.
+   */
+  icon?: string | undefined;
   /**
    * Calls to action, and the opt-in for the page's hero.
    *
@@ -122,6 +136,8 @@ interface DocNavPage {
   title: string;
   href: string;
   slug: string;
+  /** Marker name from the page's frontmatter. See {@link DocFrontmatter.icon}. */
+  icon?: string | undefined;
 }
 /**
  * A directory. `href` is present when the directory has an `index.md`, in
@@ -132,6 +148,8 @@ interface DocNavGroup {
   title: string;
   href?: string | undefined;
   children: DocNavNode[];
+  /** Marker name from the directory's `meta.json`. */
+  icon?: string | undefined;
 }
 /** A non-interactive heading between groups, from `"---Label---"` in meta.json. */
 interface DocNavSeparator {
@@ -144,6 +162,8 @@ interface DocNavLink {
   title: string;
   href: string;
   external: boolean;
+  /** Marker name from the `meta.json` entry that declared this link. */
+  icon?: string | undefined;
 }
 type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
 /**
@@ -164,10 +184,17 @@ type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
 interface DocsMeta {
   /** Directory title, shown as the group heading. Defaults to the dirname. */
   title?: string | undefined;
+  /**
+   * Sidebar marker for this directory, as a name the consumer resolves. See
+   * {@link DocFrontmatter.icon} — the same contract, declared where the
+   * directory is described rather than where a page is.
+   */
+  icon?: string | undefined;
   /** Ordered entries. Omit to sort by frontmatter `order`, then alphabetically. */
   pages?: Array<string | {
     title: string;
     href: string;
+    icon?: string | undefined;
   }> | undefined;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.7.0",
+  "version": "0.8.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": [