@waveso/docs 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,280 @@
 # @waveso/docs
 
+## 0.12.0
+
+### Minor Changes
+
+- 3551951: **The search results and the sidebar say "there is more this way" the same way
+  the table does, and hide their scrollbars where they can.**
+
+  Four gradients on the search list, exactly as `.wave-docs-table-scroll` does it:
+  the two `local` covers are painted in the surface colour and travel _with_ the
+  rows, so each sits over its shadow only while that edge is at rest, and the two
+  `scroll` shadows are pinned to the box. A grey edge appears on precisely the side
+  that has rows off-screen, with no listener, no state and no hydration.
+
+  ⚠️ IT REPLACED A MASK, WHICH WAS THE WRONG TOOL TWICE OVER. A mask fades content
+  to _transparent_, so what showed through was the dialog's own white — a hole
+  rather than a shadow. And it cannot be conditional: CSS has no way to ask whether
+  there is anything above to scroll to, so the first and last rows were softened
+  even at rest.
+
+  ## The sidebar needs its shadow above the content, not behind it
+
+  ⚠️ `.wave-docs-sidebar` PAINTS ITS OWN GROUND, AND MUST. It is in the theme's
+  opt-in rule — the one that installs a ground wherever it installs a foreground
+  ramp — so a consumer mounting the tree alone gets one, and `styles.browser.test`
+  requires the shell to be a single surface. An element's background is painted
+  _below_ its children, so the four-gradient trick was covered by a child 480px
+  tall: measured 255/255 at the top edge with the nav scrolled — declared,
+  computed, and invisible.
+
+  So the navigation's overflow moved to an inner box, `.wave-docs-layout__sidebar-scroll`,
+  and the panel keeps only its edges.
+
+  ⚠️ THAT SPLIT IS THE FIX, AND EVERY VERSION BEFORE IT FOUGHT THE SCROLLER. An
+  absolutely positioned child of a scroll container is laid out against that
+  container's padding box and _joins its scrollable overflow_ — so nothing placed
+  inside a scroller is ever pinned to it. `position: sticky` only clamps, and a
+  clamp is still a thing that travels until it catches. With the scrolling on an
+  inner element the panel is an ordinary positioned box: `top: 0` and `bottom: 0`
+  are its own edges, and the bands have no scroll to have a position within.
+
+  The timeline is declared on the scroller and `timeline-scope`d up to the panel,
+  because a `scroll-timeline` name is visible to the declaring element's
+  descendants and these pseudo-elements belong to its parent.
+
+  ⚠️ AND THE SHADOW BELONGS TO THE PANEL RATHER THAN THE TREE, because
+  `.wave-docs-sidebar` paints an opaque ground — it is in the theme's opt-in rule,
+  and the shell has to be one surface — so a background on the scroller would be
+  painted underneath it. Measured 255/255 when it was.
+
+  ⚠️ AND THE NAV'S FADE IS A LENGTH, NOT A PERCENTAGE OF THE SCROLL. The table's
+  keyframes shape their fade in percentages, which are percentages of the
+  container's _total_ scroll range — fine on a table, wrong on a navigation. A nav
+  with 1000px of scroll turns the same `2%…8%` into 20px…80px, so the shadow spends
+  eighty pixels of scrolling arriving at full strength, which reads exactly like it
+  is moving with the content rather than pinned to the edge. `animation-range: 0
+1rem` makes it the same short distance whatever the nav's height, identical on a
+  six-page site and a three-hundred-page one, with plain fades for keyframes
+  because the shaping now lives in the range.
+
+  ⚠️ THE SCROLLBAR IS HIDDEN ONLY WHERE THE SHADOW EXISTS. Both live in the same
+  `@supports (animation-timeline: scroll())`, so Firefox — where scroll-driven
+  animations have not shipped — keeps the thin bar rather than losing the bar and
+  the shadow together. A scrollbar is the one cue that a column has more below it,
+  and taking it away before something replaces it trades a slab for nothing.
+
+  ⚠️ AND A SECOND TEST LEARNED THAT `getAnimations()` IS NOT "TRANSITIONS". A
+  scroll-driven animation's `finished` promise resolves when the _scroll position_
+  reaches the end, which is to say never on a panel sitting at the top — so
+  awaiting the whole list hung `sidebar.browser.test.tsx` for its full 15s timeout
+  the moment this shadow existed. `nav.browser.test.tsx` had already been bitten by
+  the table's; this is the second place the assumption lived.
+
+- 70649b8: **Search results get a glyph, a breadcrumb, and no scrollbar.**
+
+  **A page or a section, as an icon.** Which one is read off the `href` rather
+  than a new index field — a record with an anchor is a section within a page and
+  one without is the page itself, which is what `buildSearchIndex` means by its
+  lead record — so the records did not grow by a byte.
+
+  ⚠️ AND THE ICON IS NOT DECORATION, IT IS THE ALIGNMENT. With no icon a result's
+  heading sat on the same column as the input's _magnifier_ while the input's own
+  text sat 24px right of it: three left edges where a reader expects two, which is
+  what made the dialog read as stacked levels rather than as a list under a field.
+  The icon takes the magnifier's column and the text takes the input's, so the two
+  rows are the same shape. Measured: 18px and 42px, both rows, plus the footer's
+  key caps on the 18.
+
+  **The second line is a breadcrumb.** The segments were always a trail from the
+  site's root to the page; slashes made them read as a URL to parse and `›` makes
+  them read as what they are. ⚠️ SAFE ONLY BECAUSE THAT LINE IS `aria-hidden` —
+  more than one screen reader pronounces the character, which is exactly why
+  `spokenName` joins with commas instead. The two lines carry the same fact in the
+  form each audience can use.
+
+  ⚠️ THE SEPARATOR IS THE PACKAGE'S OWN CHEVRON, NOT A CHARACTER, AND TWO
+  CHARACTERS WERE MEASURED AND REJECTED FIRST. `›` (U+203A) inks 4.93px tall in
+  the shipped mono face at 11px, against 6.32 for an `s` and 8.51 for a `b` — it
+  sat visibly below the words it separated. `❯` (U+276F) inks 8.03 and fixed the
+  height _on one machine_: `ui-monospace` resolves to SF Mono here, Consolas on
+  Windows, Liberation Mono on Linux, and a glyph missing from one of those falls
+  back to another face at another width. U+3009 already demonstrated exactly that,
+  measuring 11.24px against the 6.62 cell.
+
+  An SVG has no font to be missing from — and it is the same Lucide chevron the
+  sidebar and the pager draw, which is the real argument: everything else here is
+  that one set.
+
+  ⚠️ AND THE TRAIL IS SET IN THE SANS, NOT IN THE MONO IT STARTED IN — WHICH IS
+  WHAT MADE THE SEPARATOR RELIABLE. A monospace face advances every glyph one
+  cell, so the segments marched on a rigid grid an icon could not join, and its
+  metrics are whatever the machine resolves: SF Mono here, Consolas on Windows,
+  Liberation Mono on Linux. The cap height an inline glyph is sized against
+  therefore moved from reader to reader, which is the same portability problem
+  that ruled out `›` and `❯` as characters — arriving a second time through the
+  face rather than through the glyph. Proportional sans has ordinary spacing and
+  one set of metrics to match. `font-size` goes up a notch with it, because a
+  mono face reads larger at the same size and holding the number would have
+  shrunk the line.
+
+  ⚠️ AND THE `viewBox` IS CROPPED TO THE STROKE, WHICH IS WHAT RETIRED FOUR
+  CORRECTIONS. On Lucide's full 24 grid the chevron occupies x 9–15 and y 6–18,
+  so a square box around it was five sixths air across and half air down — and
+  every one of those gaps had to be subtracted back by hand: a `vertical-align`,
+  a negative `margin-inline`, a negative `margin-block`, and a size chosen to
+  make the surplus come out right. `8 5 8 14` is the painted extent, caps and
+  joins included. The box is the glyph, so it sits on the baseline the way a
+  letter does with nothing declared, and the air beside it is one positive
+  `margin-inline`.
+
+  ⚠️ AND IT CARRIES `overflow: visible`, WITHOUT WHICH THE POINT IS FLAT. An
+  `svg` clips to its viewport by default and this `viewBox` is exactly the
+  stroke's extent, so the round join at the tip lands on the box's own edge and
+  loses its outermost anti-aliased pixel. Nothing overlaps anything: what spills
+  is a fraction of a pixel.
+
+  ## The scrollbar is hidden, and it cannot be conditional
+
+  ⚠️ THERE IS NO CSS WAY TO SHOW A SCROLLBAR ONLY WHILE SCROLLING. That behaviour
+  is the platform's: macOS draws overlay scrollbars that fade in on scroll and out
+  after it, and this list gets it for free there. Windows and Linux draw a classic
+  one that is always present, and the only ways to make it come and go are a
+  JavaScript timer toggling a class or a scrollbar drawn from scratch in script —
+  which is what a `ScrollArea` component is, and neither belongs in a package whose
+  whole argument is what it does _not_ ship to a reader.
+
+  So it is hidden, as `@waveso/app` does with `.scrollbar-none`. What replaces it
+  is the keyboard rather than a fade: the footer says `↑ ↓ Select`, the list is
+  driven by `aria-activedescendant`, and arrowing past the last visible row scrolls
+  it and loads the next page.
+
+  ⚠️ AND `pageSize` STAYS A WINDOW, NOT A CAP. It was a hard ceiling of 8 once, and
+  that was removed with measurements: on a six-page site "docs" matches 18, so
+  results were unreachable and the live region announced "8 results" — not a
+  smaller truth but a false one. Rendering every row of a 300-page corpus costs
+  40ms, 128ms at 4x throttle, which is what paging exists to avoid; the ceiling
+  was never what made it fast.
+
+  The size budget moves with the glyphs, and the figures the README and the
+  installation page publish move with it — a document here may not understate what
+  this package costs.
+
+- 78053a6: **Nothing in the search dialog is selected until the reader selects it.**
+
+  Typing lit the first result the instant it arrived, so a row changed under a
+  reader for something they had not chosen — and on this package's accent that
+  reads as a decision already made. `activeIndex` starts at `-1` now: an arrow key
+  or the pointer moving over a row is what selects.
+
+  ⚠️ AND EVERY GUARD FOR IT ALREADY EXISTED, WHICH IS WHY THIS IS ONE NUMBER.
+  `hits[-1]` is `undefined`, so no `aria-activedescendant` is written and Enter
+  returns without opening anything. The one place that needed teaching is the
+  arrow keys: they wrap modulo the list, and `(-1 - 1 + n) % n` is the _second to
+  last_, so Up from a fresh query landed one short of the end.
+
+  **The active row is the table header's grey**, easing on the same 150ms the
+  sidebar's rows use. Moving the pointer over a result activates it, so hovering
+  _is_ this state; there is no second rule for it.
+
+  It has been four things: a 2px accent ring, which read as a component borrowed
+  from somewhere else and came and went as a reader arrowed; the trigger's border
+  pair, which meant bordering _every_ row to make one edge legible and turned a
+  list into a stack of cards; an accent tint, which was the same colour family as
+  the field above it. A row is a list item and its state is a colour — the field is
+  a control, and that is what wears the trigger's border.
+
+  ⚠️ `bg-subtle` ON `bg` IS ABOUT 1.02:1, SO THE TINT IS A HINT AND NOT AN
+  INDICATOR. The marker going `fg-subtle` to `fg` is the part that carries the
+  state — text contrast rather than non-text, and the sidebar's own hover. What
+  must not happen is the tint being left to carry it alone.
+
+  ## The field stops drawing a ring it could never put down
+
+  ⚠️ A TEXT INPUT MATCHES `:focus-visible` WHENEVER IT IS FOCUSED, HOWEVER FOCUS
+  ARRIVED — that is the spec, not a heuristic — and this dialog focuses its input
+  the moment it opens. So the accent ring was not a state, it was the field's
+  permanent appearance, and it stopped the field looking like the bordered grey
+  control the reader clicked to get there.
+
+  The edge darkens to `--wave-docs-border-strong` instead, which is what the
+  trigger does under the pointer, so the field is the trigger in both of its
+  states.
+
+  ⚠️ AND THE INDICATOR IS NOT LOST WITH IT, BECAUSE A TEXT FIELD HAS ONE OF ITS
+  OWN. The caret is the platform's focus indication for a text box, it is in this
+  field the whole time the dialog is open, and it is what a reader looks for to see
+  where typing goes. That is a different argument from the one this rule used to
+  reject: "the dialog frame is the indicator" was a _static_ border that looked
+  identical focused and unfocused, and indicated nothing. This edge changes.
+
+  ## The list fades at both edges
+
+  A mask on the scrollport, so the row being cut off is the one that softens. It
+  does not travel with the content: a mask paints against the element's own box, so
+  the two stops stay at the top and bottom of the _port_ while the rows move under
+  them.
+
+  ⚠️ IT IS UNCONDITIONAL, WHICH IS THE ONE THING TO KNOW. CSS cannot ask "is there
+  anything above this to scroll to" — the table's shadow answers that with a
+  scroll-driven animation whose timeline goes inactive when nothing overflows, and
+  a mask has no equivalent. So the first and last rows carry a little of it at
+  rest. At `1.25rem` against a row nearer three times that, it costs the top pixel
+  or two of a heading and buys never guillotining one.
+
+  ## The field, and the gap under it
+
+  **The field is the trigger, expanded.** Same border, same fill, same radius. It
+  was a border with no fill — two frames a few pixels apart — and briefly a fill
+  with no border, which is a tinted band rather than a control. The trigger has
+  always been both, and both together are what reads as a field.
+
+  ⚠️ THE PADDING IS NOT COPIED WITH THEM. The trigger pays `calc(0.5rem - 1px)`
+  because it is a compact control in a sidebar; the field pays
+  `calc(0.75rem - 1px)` because its glyph has to land on the column the results
+  and the footer sit on. The `- 1px` is the border either way — content inside a
+  bordered box starts a border further in.
+
+  The field takes the base radius and the result rows take `-sm`, which is the tier
+  system doing what it says: both are controls, and a result row is a list item.
+
+  ⚠️ AND THE GAP UNDER THE FIELD WAS PAID TWICE. The field's margin and the result
+  list's top padding both contributed, so the space between the input and the first
+  result was double the space above the input — a doubled gap in the one place a
+  reader's eye travels on every keystroke. The list drops its top padding; the
+  field keeps its margin, because an empty result list is `display: none` and a gap
+  paid from there would vanish on the query that matches nothing.
+
+### Patch Changes
+
+- 688a84c: **The search dialog lines up on one column, and its input is a field rather
+  than a band.**
+
+  The input row was flush to the dialog's frame, so it could only round the two
+  corners it shared with it and needed a rule underneath to separate it from the
+  results. Inset by the same margin the results list uses, it is a box like they
+  are — all four corners rounded, and the gap does the separating.
+
+  ⚠️ AND ITS RADIUS IS THE DIALOG'S MINUS THE GAP, NOT THE DIALOG'S. A rounded box
+  inset inside a rounded box is concentric only at `outer - gap`; equal radii run
+  the two corners at different curvatures six pixels apart and the field reads as
+  pasted onto the dialog rather than set into it.
+
+  **One column, measured from the bottom up.** The footer's key caps are the
+  anchor — the one row whose left edge is a drawn object — and the results' text
+  and the input's magnifier are measured to it. All three now start 18px from the
+  dialog's inner edge.
+
+  ⚠️ BOXES, NOT INK. A cap's arrow sits its own border and `0.4em` of padding
+  inside the cap, so aligning the _glyphs_ would put every other row on a column
+  that moves whenever the footer's font size does.
+
+  ⚠️ AND THE INPUT ROW PAYS `calc(0.75rem - 1px)` BECAUSE IT IS THE ONE ROW WITH A
+  BORDER. Content inside a bordered box starts a border further in than content
+  inside an unbordered one, so equal padding misses by exactly that — the same
+  subtraction `--wave-docs-panel-inset` exists for.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -69,8 +69,8 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | At most |
 | --- | --- |
-| Everything the quick start ships, gzipped | 14.6 KB |
-| Search dialog and router wiring | 9.5 KB |
+| Everything the quick start ships, gzipped | 14.9 KB |
+| Search dialog and router wiring | 9.8 KB |
 | Navigation: one sidebar, open and closed | 3.1 KB |
 | Table of contents | 1 KB |
 | Copy-button runtime | 1.1 KB |
@@ -78,7 +78,7 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 | 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 14.6 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.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 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.
 

package/dist/react/nav.js

@@ -86,21 +86,24 @@ function DocsNav({ nav, pathname, Link, label = "Documentation", children, close
 		className: "wave-docs-layout__sidebar",
 		...state === void 0 ? {} : { "data-state": state ? "open" : "closed" },
 		...ready ? { "data-ready": "" } : {},
-		children: [/* @__PURE__ */ jsxs("div", {
+		children: [/* @__PURE__ */ jsx("div", {
 			ref: navRef,
 			id: DOCS_NAV_ID,
 			className: "wave-docs-layout__sidebar-nav",
 			tabIndex: -1,
-			children: [children, /* @__PURE__ */ jsx(DocsSidebar, {
-				nav,
-				pathname,
-				label,
-				Link,
-				...expandGroup === void 0 ? {} : { expandGroup },
-				...collapseGroup === void 0 ? {} : { collapseGroup },
-				...externalLink === void 0 ? {} : { externalLink },
-				...icons === void 0 ? {} : { icons }
-			})]
+			children: /* @__PURE__ */ jsxs("div", {
+				className: "wave-docs-layout__sidebar-scroll",
+				children: [children, /* @__PURE__ */ jsx(DocsSidebar, {
+					nav,
+					pathname,
+					label,
+					Link,
+					...expandGroup === void 0 ? {} : { expandGroup },
+					...collapseGroup === void 0 ? {} : { collapseGroup },
+					...externalLink === void 0 ? {} : { externalLink },
+					...icons === void 0 ? {} : { icons }
+				})]
+			})
 		}), /* @__PURE__ */ jsx("button", {
 			type: "button",
 			className: "wave-docs-layout__sidebar-trigger",

package/dist/react/search-dialog.js

@@ -1,7 +1,7 @@
 "use client";
 import { docsError } from "../docs-error.js";
 import { mergeSearchOptions } from "../search-options.js";
-import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useId, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
 //#region src/react/search-dialog.tsx
@@ -51,7 +51,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	* not itself cause a render.
 	*/
 	const movedByKeyboard = useRef(false);
-	const [activeIndex, setActiveIndex] = useState(0);
+	const [activeIndex, setActiveIndex] = useState(-1);
 	const [status, setStatus] = useState("idle");
 	/**
 	* The trigger's shortcut, split rather than held as one string.
@@ -166,13 +166,13 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		if (isOpen) return;
 		setQuery("");
 		setHits([]);
-		setActiveIndex(0);
+		setActiveIndex(-1);
 	}, [isOpen]);
 	useEffect(() => {
 		const trimmed = query.trim();
 		if (trimmed.length < minQueryLength) {
 			setHits([]);
-			setActiveIndex(0);
+			setActiveIndex(-1);
 			setVisibleCount(pageSize);
 			return;
 		}
@@ -182,7 +182,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 				if (isCancelled) return;
 				setStatus("ready");
 				setHits(index.search(trimmed).map(toSearchHit).filter(isSearchHit));
-				setActiveIndex(0);
+				setActiveIndex(-1);
 				setVisibleCount(pageSize);
 			}, () => {
 				if (!isCancelled) setStatus("error");
@@ -261,7 +261,10 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			event.preventDefault();
 			const delta = event.key === "ArrowDown" ? 1 : -1;
 			movedByKeyboard.current = true;
-			setActiveIndex((index) => (index + delta + hits.length) % hits.length);
+			setActiveIndex((index) => {
+				if (index < 0) return delta > 0 ? 0 : hits.length - 1;
+				return (index + delta + hits.length) % hits.length;
+			});
 			return;
 		}
 		if (event.key === "Enter") {
@@ -446,13 +449,16 @@ function SearchResultOption({ hit, id, isActive, setSize, posInSet, onActivate,
 		event.preventDefault();
 		onSelect(hit);
 	}
-	const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
-		className: "wave-docs-search-result-heading",
-		children: hit.heading
-	}), /* @__PURE__ */ jsx("span", {
-		className: "wave-docs-search-result-location",
-		"aria-hidden": "true",
-		children: toDisplayPath(hit.href)
+	const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ResultIcon, { section: hit.href.includes("#") }), /* @__PURE__ */ jsxs("span", {
+		className: "wave-docs-search-result-text",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "wave-docs-search-result-heading",
+			children: hit.heading
+		}), /* @__PURE__ */ jsx("span", {
+			className: "wave-docs-search-result-location",
+			"aria-hidden": "true",
+			children: toDisplaySegments(hit.href).map((segment, index, all) => /* @__PURE__ */ jsxs(Fragment, { children: [index === 0 ? null : /* @__PURE__ */ jsx(PathChevron, {}), segment] }, all.slice(0, index + 1).join("/")))
+		})]
 	})] });
 	return /* @__PURE__ */ jsx("div", {
 		id,
@@ -599,9 +605,10 @@ function isSearchHit(hit) {
 * Display only. `hit.href` keeps the anchor, so the link still deep-links to
 * the section — that is the whole point of section-scoped records.
 */
-function toDisplayPath(href) {
+function toDisplaySegments(href) {
 	const hash = href.indexOf("#");
-	return hash === -1 ? href : href.slice(0, hash);
+	const segments = (hash === -1 ? href : href.slice(0, hash)).split("/").filter(Boolean);
+	return segments.length === 0 ? ["/"] : segments;
 }
 /**
 * What a result is called when it is read aloud.
@@ -618,6 +625,71 @@ function toDisplayPath(href) {
 * A page's own record carries `heading === title` and no ancestors, so its name
 * is the heading alone — "Styling, Styling" is not a path, it is a stutter.
 */
+/**
+* A page or a section, as one Lucide glyph.
+*
+* ⚠️ THE PATHS ARE WRITTEN OUT RATHER THAN IMPORTED FROM THE SIDEBAR, WHICH
+* HAS THE SAME PAGE ICON. `NAV_ICON_PATHS` lives in a different client
+* component, and importing across the two would pull the whole navigation
+* tree into the search dialog's bundle to reuse one string. The duplication is
+* two path strings; the alternative is kilobytes.
+*/
+const RESULT_ICON_PATHS = {
+	page: ["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"],
+	section: [
+		"M4 9h16",
+		"M4 15h16",
+		"m10 3-2 18",
+		"m16 3-2 18"
+	]
+};
+/**
+* The separator between two route segments.
+*
+* The same path the sidebar's group toggle and the pager draw, at the same
+* `1rem` they draw it. Decorative, and inside a span that is already
+* `aria-hidden` — the route is announced as words by `spokenName`, never read
+* out as punctuation.
+*
+* ⚠️ THE `viewBox` IS CROPPED HORIZONTALLY AND THAT IS NOT A DIFFERENT GLYPH.
+* `d` is Lucide's chevron unchanged and `8 0 8 24` keeps its vertical grid, so
+* the stroke ratio and the ink are exactly what the sidebar and the pager
+* paint. What it drops is the padding either side that the path never reaches:
+* on the full grid a 24-unit box held six units of chevron, so five-sixths of
+* this element was air and the stylesheet had to subtract it back with
+* negative margins. Cropped, the box is the ink and the spacing beside it is
+* one positive value. See `.wave-docs-search-result-sep`.
+*/
+function PathChevron() {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-search-result-sep",
+		"aria-hidden": "true",
+		focusable: "false",
+		viewBox: "8 5 8 14",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+	});
+}
+function ResultIcon({ section }) {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-search-result-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: RESULT_ICON_PATHS[section ? "section" : "page"].map((d) => /* @__PURE__ */ jsx("path", { d }, d))
+	});
+}
 function spokenName(hit) {
 	if (hit.ancestors.length === 0 && hit.heading === hit.title) return hit.heading;
 	return [

package/dist/styles.css

@@ -2173,7 +2173,16 @@
      */
     .wave-docs-sidebar__link,
     .wave-docs-sidebar__group-button,
-    .wave-docs-sidebar__group-toggle {
+    .wave-docs-sidebar__group-toggle,
+    /*
+     * A search result is the same object as a sidebar row — a link that tints
+     * under the pointer — so it eases the same way. Moving over a result
+     * *activates* it, which is why there is no separate hover rule to ease:
+     * the state below is both.
+     */
+    .wave-docs-search-result,
+    .wave-docs-search-result-heading,
+    .wave-docs-search-result-icon {
       transition:
         background-color 150ms ease-out,
         color 150ms ease-out;
@@ -3263,7 +3272,17 @@
     flex: none;
     box-sizing: border-box;
     width: var(--wave-docs-sidebar-width);
-    padding: 2rem 1rem;
+    /*
+     * ⚠️ NO PADDING AND NO OVERFLOW HERE — BOTH MOVED INTO
+     * `.wave-docs-layout__sidebar-scroll`, AND THAT SPLIT IS THE POINT.
+     *
+     * This panel is now an ordinary positioned box that happens to be sticky,
+     * so the edge shadows below resolve against it and have nothing to scroll
+     * with. While it was the scroll container itself they had to be
+     * `position: sticky` and cancel its padding by hand, and every version of
+     * that fought the scroller rather than standing outside it.
+     */
+    overflow: hidden;
     border: 0;
     /*
      * Cover mode only, and it is a different thing from the divider in push
@@ -3279,10 +3298,6 @@
     position: sticky;
     top: var(--wave-docs-chrome-offset);
     height: calc(100dvh - var(--wave-docs-chrome-offset));
-    overflow-y: auto;
-    /* Without this, reaching the end of the nav keeps scrolling — the article
-     * jumps under the reader's cursor while they are looking at the sidebar. */
-    overscroll-behavior: contain;
     /*
      * ⚠️ NO `scrollbar-gutter: stable`, AND IT USED TO HAVE ONE.
      *
@@ -3299,11 +3314,196 @@
      *
      * `thin`, so the scrollbar that does appear is narrow, and coloured rather
      * than left as the UA's default slab against the panel.
+     *
+     * ⚠️ AND IT IS HIDDEN ONLY WHERE SOMETHING REPLACES IT — see the `@supports`
+     * block below. A bar is the one cue that a column has more below it, so
+     * taking it away before the shadow exists trades a slab for nothing.
      */
     scrollbar-width: thin;
     scrollbar-color: var(--wave-docs-border-strong) transparent;
   }
 
+  .wave-docs-layout__sidebar-scroll {
+    height: 100%;
+    overflow-y: auto;
+    /* Without this, reaching the end of the nav keeps scrolling — the article
+     * jumps under the reader's cursor while they are looking at the sidebar. */
+    overscroll-behavior: contain;
+    padding: 2rem 1rem;
+    scrollbar-width: inherit;
+    scrollbar-color: inherit;
+  }
+
+  /*
+   * ⚠️ ABSOLUTE AGAINST THE PANEL, WHICH IS NOT THE SCROLLER — AND THAT IS THE
+   * WHOLE REASON THIS FINALLY HOLDS STILL.
+   *
+   * These were `position: sticky` inside the scroll container, cancelling its
+   * padding by hand, and they still read as moving. An absolutely positioned
+   * child of a scroll container is laid out against that container's padding
+   * box and joins its scrollable overflow, so nothing placed inside the
+   * scroller is ever truly pinned to the panel; sticky only clamps it, and a
+   * clamp is still a thing that travels until it catches.
+   *
+   * With the overflow moved to `.wave-docs-layout__sidebar-scroll`, the panel is
+   * an ordinary positioned box. `top: 0` and `bottom: 0` are its own edges, and
+   * there is no scroll for these to have a position within.
+   *
+   * ⚠️ AND THE SHADOW STILL BELONGS TO THE PANEL RATHER THAN THE TREE, because
+   * `.wave-docs-sidebar` paints an opaque ground — it is in the theme's opt-in
+   * rule, and the shell has to be one surface — so a background on the scroller
+   * would be painted underneath it. Measured 255/255 when it was.
+   */
+  .wave-docs-layout__sidebar-nav::before,
+  .wave-docs-layout__sidebar-nav::after {
+    content: '';
+    position: absolute;
+    inset-inline: 0;
+    z-index: 1;
+    height: 0.75rem;
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .wave-docs-layout__sidebar-nav::before {
+    top: 0;
+    /*
+     * Radial, the shape the table and the search list use: strongest against
+     * the edge it belongs to and falling away from it, rather than a flat ramp
+     * across the band.
+     */
+    background: radial-gradient(
+      farthest-side at 50% 0,
+      var(--wave-docs-scroll-shadow),
+      transparent
+    );
+  }
+
+  .wave-docs-layout__sidebar-nav::after {
+    bottom: 0;
+    background: radial-gradient(
+      farthest-side at 50% 100%,
+      var(--wave-docs-scroll-shadow),
+      transparent
+    );
+  }
+
+  /*
+   * ⚠️ AN INACTIVE TIMELINE IS WHAT MAKES THIS CORRECT. A scroll timeline is
+   * inactive when its container has no scrollable overflow in the axis, and an
+   * animation with an inactive timeline does not apply — so `opacity: 0` wins
+   * and a nav that fits shows nothing at all. No query asks whether it scrolls;
+   * the answer falls out of whether there is anything to scroll.
+   *
+   * ⚠️ `nearest`, NOT `self`: the animation is on a pseudo-element *inside* the
+   * scroll container rather than on the container itself, and `self` would name
+   * the pseudo — inactive at every height, which looks exactly like the feature
+   * being unsupported.
+   *
+   * The scrollbar is hidden in here and nowhere else. Where this does not run —
+   * Firefox, until scroll-driven animations ship — the thin bar above stays and
+   * a reader keeps the cue rather than losing both.
+   */
+  @supports (animation-timeline: scroll()) {
+    .wave-docs-layout__sidebar-scroll {
+      scrollbar-width: none;
+    }
+
+    .wave-docs-layout__sidebar-scroll::-webkit-scrollbar {
+      display: none;
+    }
+
+    /*
+     * ⚠️ A NAMED TIMELINE, AND `scroll(nearest block)` WAS A REAL BUG RATHER
+     * THAN A TIDIER SPELLING.
+     *
+     * `nearest` means the nearest ancestor *scroll container*, and a box is
+     * only one when it actually has scrollable overflow. This nav is a screen
+     * tall and on most sites its tree fits — measured `scrollHeight -
+     * clientHeight === 0` at 1440×900 on this very site — so `nearest` walked
+     * straight past it and found the document, which always scrolls.
+     *
+     * The result was the shadow keyed to the *page*: it faded in as the reader
+     * scrolled the article, on a navigation with nothing hidden, while the
+     * sticky panel was still travelling to its pinned position. Appearing and
+     * moving at once, which is precisely what it looked like.
+     *
+     * Named, it can only ever be this element's own scroll. And the
+     * inactive-timeline rule then does the right thing for free: a nav that
+     * fits declares a timeline with no scroll range, the animation does not
+     * apply, and `opacity: 0` wins.
+     */
+    /*
+     * ⚠️ THE TIMELINE IS DECLARED ON THE SCROLLER AND *SCOPED* UP TO THE PANEL,
+     * because the two are different elements now. A `scroll-timeline` name is
+     * visible to the declaring element's descendants, and these pseudo-elements
+     * belong to its parent — so without `timeline-scope` they would not find it
+     * and would sit at `opacity: 0` for ever, looking exactly like the feature
+     * being unsupported.
+     */
+    .wave-docs-layout__sidebar-nav {
+      timeline-scope: --wave-docs-sidebar-nav-scroll;
+    }
+
+    .wave-docs-layout__sidebar-scroll {
+      scroll-timeline: --wave-docs-sidebar-nav-scroll block;
+    }
+
+    .wave-docs-layout__sidebar-nav::before,
+    .wave-docs-layout__sidebar-nav::after {
+      animation-timeline: --wave-docs-sidebar-nav-scroll;
+      animation-timing-function: linear;
+      animation-fill-mode: both;
+    }
+
+    /*
+     * ⚠️ THE RANGE IS A LENGTH, NOT THE WHOLE SCROLL — AND THAT IS WHAT STOPS
+     * THIS RAMPING WHILE THE READER SCROLLS.
+     *
+     * `wave-docs-scroll-shadow-start` shapes its fade in *percentages*, which
+     * are percentages of the container's total scroll range. That is fine on a
+     * table, which scrolls a few hundred pixels; on a navigation it is not. A
+     * nav with 1000px of scroll turns the same `2%…8%` into 20px…80px, so the
+     * shadow spends eighty pixels of scrolling getting to full strength —
+     * arriving gradually, which reads exactly like it is moving with the
+     * content rather than pinned to the edge.
+     *
+     * A fixed `1rem` makes it the same short distance whatever the nav's
+     * height: present almost at once, and identical on a six-page site and a
+     * three-hundred-page one. The keyframes are plain fades because the shaping
+     * now lives in the range.
+     */
+    .wave-docs-layout__sidebar-nav::before {
+      animation-name: wave-docs-scroll-shadow-appear;
+      animation-range: 0 1rem;
+    }
+
+    .wave-docs-layout__sidebar-nav::after {
+      animation-name: wave-docs-scroll-shadow-vanish;
+      animation-range: calc(100% - 1rem) 100%;
+    }
+  }
+
+  /* Absent at the start edge, present as soon as it is not. */
+  @keyframes wave-docs-scroll-shadow-appear {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  /* Present until the end edge is reached. */
+  @keyframes wave-docs-scroll-shadow-vanish {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+    }
+  }
+
   /* First child of the navigation, above the tree. */
   .wave-docs-layout__search {
     margin-block-end: 1rem;
@@ -3913,34 +4113,87 @@
     box-shadow: 0 24px 48px -12px var(--wave-docs-shadow);
   }
 
+  /*
+   * ⚠️ A FIELD SET INTO THE DIALOG, AND IT WAS A FULL-BLEED BAND WITH TWO
+   * ROUNDED CORNERS AND A RULE UNDER IT.
+   *
+   * Flush to the frame it could only round the corners it shared with the
+   * dialog, so it read as part of the chrome rather than as the one control in
+   * it. Inset by the same margin the results list uses, it is a box like they
+   * are, and the rule under it is redundant — the gap does that work.
+   *
+   * ⚠️ AND THE `- 1px` IS THIS BOX'S OWN BORDER, WHICH IS WHAT PUTS ITS GLYPH
+   * ON THE SAME COLUMN AS EVERYTHING ELSE. Content inside a bordered box starts
+   * a border further in than content inside an unbordered one, so equal padding
+   * misses by exactly that. The same subtraction `--wave-docs-panel-inset`
+   * documents, for the same reason.
+   */
   .wave-docs-search-input-row {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    padding: 0.75rem;
-    border-block-end: 1px solid var(--wave-docs-border);
-    /* Matches the dialog's corners, so the focus ring below traces them
-     * instead of poking out of the rounded frame. */
-    border-start-start-radius: var(--wave-docs-radius);
-    border-start-end-radius: var(--wave-docs-radius);
-  }
-
-  /* The ring belongs to the row, not the input. A 2px ring drawn around a
-   * borderless full-width input reads as an error state, and the previous
-   * answer — "the dialog frame is the indicator" — was a static 1.31:1 border
-   * that looks identical focused and unfocused (WCAG 2.4.7 wants a change of
-   * appearance, 1.4.11 wants 3:1; `accent` on `bg` is 5.16:1 / 7.50:1).
-   * `outline-offset: -2px` draws it inward, because the dialog clips with
-   * `overflow: hidden` and an outward ring would be sliced off. */
+    margin: 0.375rem;
+    /*
+     * ⚠️ THE TRIGGER, EXPANDED — SAME BORDER, SAME FILL, SAME RADIUS.
+     *
+     * A reader clicks a bordered, filled control and lands in this dialog, so
+     * the thing their cursor is now in should be the same object. It was a
+     * border with no fill (two frames a few pixels apart), then a fill with no
+     * border (a tinted band, not a control); the trigger has always been both,
+     * and both together are what reads as a field.
+     *
+     * ⚠️ THE PADDING IS NOT COPIED WITH THEM. The trigger pays
+     * `calc(0.5rem - 1px)` because it is a compact control in a sidebar; this
+     * pays `calc(0.75rem - 1px)` because its glyph has to land on the column
+     * the results and the footer sit on. The `- 1px` is the border either way:
+     * content inside a bordered box starts a border further in.
+     *
+     * ⚠️ AND THE RADIUS IS THE TRIGGER'S TIER, NOT THE ROWS'. Both are controls
+     * on the base tier; a result row is a list item on `-sm`. So the field is
+     * 16px and the rows below it are 12px, which is the tier system doing what
+     * it says rather than two boxes disagreeing.
+     */
+    padding: 0.5rem calc(0.75rem - 1px);
+    border: 1px solid var(--wave-docs-border);
+    border-radius: var(--wave-docs-radius);
+    background: var(--wave-docs-bg-subtle);
+  }
+
+  /*
+   * ⚠️ THE FIELD DARKENS ITS EDGE ON FOCUS — IT DOES NOT DRAW AN ACCENT RING,
+   * AND IT CANNOT, BECAUSE IT COULD NEVER PUT ONE DOWN.
+   *
+   * A text input matches `:focus-visible` whenever it is focused, however
+   * focus arrived — that is the spec, not a heuristic — and this dialog focuses
+   * its input the moment it opens. So a 2px accent ring here is not a state, it
+   * is the field's permanent appearance, and the field stops looking like the
+   * bordered grey control the reader clicked to get here.
+   *
+   * ⚠️ AND THE INDICATOR IS NOT LOST WITH IT, BECAUSE A TEXT FIELD HAS ONE OF
+   * ITS OWN. The caret is the platform's focus indication for a text box, it is
+   * in this field the whole time the dialog is open, and it is the thing a
+   * reader looks for when they want to know where typing goes. That is a
+   * different argument from the one this rule used to reject — "the dialog
+   * frame is the indicator" was a *static* border that looked identical focused
+   * and unfocused, indicating nothing.
+   *
+   * The edge still changes, to the same `border-strong` the trigger takes under
+   * the pointer, so the field is the trigger in both of its states.
+   */
   .wave-docs-search-input-row:has(.wave-docs-search-input:focus-visible) {
-    outline: 2px solid var(--wave-docs-accent);
-    outline-offset: -2px;
+    border-color: var(--wave-docs-border-strong);
   }
 
   .wave-docs-search-input {
     flex: 1 1 auto;
     min-width: 0;
-    padding: 0.375rem 0.25rem;
+    /*
+     * ⚠️ NO INLINE PADDING, BECAUSE THIS BOX'S EDGE IS A COLUMN THE RESULTS
+     * MEASURE TO. Four pixels here put the typed text four pixels right of
+     * every result heading below it, which is the sort of misalignment that
+     * looks like a bug in the list rather than a padding on the field.
+     */
+    padding: 0.375rem 0;
     border: 0;
     background: none;
     color: var(--wave-docs-fg);
@@ -3973,7 +4226,18 @@
     display: flex;
     align-items: center;
     gap: 1rem;
-    padding: 0.5rem 0.75rem;
+    /*
+     * ⚠️ THE COLUMN EVERY OTHER ROW IN THIS DIALOG LINES UP ON, AND IT IS THE
+     * ANCHOR RATHER THAN A FOLLOWER. The key caps are the one row whose left
+     * edge is a drawn object, so the input's glyph and the results' text are
+     * measured to it: `0.375rem` of inset plus `0.75rem` of padding is the same
+     * 18px this pays in one go.
+     *
+     * Boxes, not ink. A cap's arrow sits its own border and `0.4em` of padding
+     * inside the cap, so aligning the *glyphs* would put every other row on a
+     * column that moves whenever the footer's font size does.
+     */
+    padding: 0.5rem 1.125rem;
     border-block-start: 1px solid var(--wave-docs-border);
     color: var(--wave-docs-fg-subtle);
     font-size: 0.75rem;
@@ -4059,7 +4323,75 @@
   .wave-docs-search-results {
     flex: 1 1 auto;
     overflow-y: auto;
-    padding: 0.375rem;
+    /*
+     * ⚠️ THE TABLE'S SCROLL SHADOW, TURNED ON ITS SIDE — AND IT REPLACED A
+     * MASK, WHICH WAS THE WRONG TOOL TWICE OVER.
+     *
+     * A mask fades content to *transparent*, so what showed through was the
+     * dialog's own white: a hole rather than a shadow. And it cannot be
+     * conditional — CSS has no way to ask whether there is anything above to
+     * scroll to — so the first and last rows were softened even at rest.
+     *
+     * Four gradients, exactly as `.wave-docs-table-scroll` does it. The two
+     * `local` covers are painted in the surface colour and travel *with* the
+     * rows, so each sits over its shadow only while that edge is at rest; the
+     * two `scroll` shadows are pinned to the box. A grey edge appears on
+     * precisely the side that has rows off-screen, with no listener, no state
+     * and no hydration.
+     */
+    background:
+      linear-gradient(to bottom, var(--wave-docs-bg) 30%, transparent) top /
+        100% 2rem no-repeat local,
+      linear-gradient(to top, var(--wave-docs-bg) 30%, transparent) bottom /
+        100% 2rem no-repeat local,
+      radial-gradient(
+          farthest-side at 50% 0,
+          var(--wave-docs-scroll-shadow),
+          transparent
+        )
+        top / 100% 0.75rem no-repeat scroll,
+      radial-gradient(
+          farthest-side at 50% 100%,
+          var(--wave-docs-scroll-shadow),
+          transparent
+        )
+        bottom / 100% 0.75rem no-repeat scroll;
+    /*
+     * ⚠️ NO PADDING ON TOP, BECAUSE THE FIELD'S MARGIN IS ALREADY THAT GAP.
+     * Both paid it, so the space between the input and the first result was
+     * twice the space between the input and the top of the dialog — a
+     * doubled gap in the one place a reader's eye travels on every keystroke.
+     *
+     * Kept on the *bottom*, where nothing else pays it, and on the sides,
+     * where it is what lines a row's box up with the field's.
+     *
+     * ⚠️ AND IT IS THE FIELD THAT KEEPS ITS MARGIN RATHER THAN THIS THAT KEEPS
+     * ITS PADDING. An empty result list is `display: none`, so a gap paid from
+     * here would vanish on the query that matches nothing and leave the field
+     * sitting on the footer's rule.
+     */
+    padding: 0 0.375rem 0.375rem;
+    /*
+     * ⚠️ NO SCROLLBAR, AND NO CSS WAY TO SHOW ONE ONLY WHILE SCROLLING.
+     *
+     * That behaviour is the platform's: macOS draws overlay scrollbars that
+     * fade in on scroll and out after it, and this list gets it for free there.
+     * Windows and Linux draw a classic one that is always present, and nothing
+     * in CSS can make it come and go — the only ways are a JavaScript timer
+     * that toggles a class, or a scrollbar drawn from scratch in script, which
+     * is what a `ScrollArea` component is. Neither belongs in a package whose
+     * whole argument is what it does *not* ship to a reader.
+     *
+     * So it is hidden, which is what `@waveso/app` does with `.scrollbar-none`.
+     * What replaces it here is not a fade but the keyboard: the footer says
+     * `↑ ↓ Select`, the list is driven by `aria-activedescendant`, and arrowing
+     * past the last visible row scrolls it and loads the next page.
+     */
+    scrollbar-width: none;
+  }
+
+  .wave-docs-search-results::-webkit-scrollbar {
+    display: none;
   }
 
   /*
@@ -4076,29 +4408,104 @@
     border-radius: var(--wave-docs-radius-sm);
   }
 
-  /* Driven by `aria-selected` through the active class the dialog sets — the
-   * combobox keeps focus in the input and every result is `tabindex="-1"`, so
-   * `:focus-visible` can never fire here and the tint IS the whole indicator.
-   * A tint alone is 1.12:1 light / 1.19:1 dark; WCAG 1.4.11 asks 3:1 of a
-   * state indicator, so the outline carries it (`accent` on `accent-subtle` is
-   * 4.60:1 / 6.30:1) and the tint is left to do the soft work. Inset by 2px so
-   * it stays inside the scrolling results list. */
+  /*
+   * The active row, driven by `aria-selected` through the class the dialog
+   * sets — so the visual state and the announced state cannot drift apart.
+   * Pointer and keyboard land on the same state: moving over a row activates
+   * it, so hovering *is* this.
+   *
+   * ⚠️ A TINT AND AN INK, AND NO EDGE IN ANY STATE. It was a 2px accent ring,
+   * and briefly the trigger's border pair. The ring read as a component
+   * borrowed from somewhere else and one that comes and goes as a reader
+   * arrows is worse than one that never moves; bordering *every* row to make
+   * the active one's edge legible turned a list into a stack of cards. The
+   * field above wears the trigger's border because the field is a control; a
+   * row is a list item, and its state is a colour.
+   *
+   * ⚠️ THE INK IS NOT DECORATION — IT IS WHAT KEEPS THE STATE PERCEIVABLE. A
+   * tint alone is 1.12:1 light and 1.19:1 dark, under the 3:1 WCAG 1.4.11 asks
+   * of a state indicator. `accent` on `accent-subtle` is 4.60:1 / 6.30:1, which
+   * is text contrast rather than non-text and is the same pair the sidebar's
+   * current-page row has always shipped. What must not happen is the tint going
+   * back to carrying this alone.
+   */
   .wave-docs-search-result-active {
     background: var(--wave-docs-accent-subtle);
-    outline: 2px solid var(--wave-docs-accent);
-    outline-offset: -2px;
   }
 
+  .wave-docs-search-result-active .wave-docs-search-result-heading,
+  .wave-docs-search-result-active .wave-docs-search-result-icon {
+    color: var(--wave-docs-accent);
+  }
+
+  /*
+   * ⚠️ A ROW OF TWO COLUMNS, AND IT WAS ONE STACKED COLUMN.
+   *
+   * The dialog reads as one grid only if the input and the results agree about
+   * *both* their columns. With no icon, a result's heading sat on the same
+   * column as the input's magnifier while the input's own text sat 24px right
+   * of it — three left edges where a reader expects two, which is what made the
+   * dialog look like stacked levels rather than a list under a field.
+   *
+   * The icon takes the magnifier's column and the text takes the input's, so
+   * the two rows are the same shape and there are exactly two edges.
+   */
   .wave-docs-search-result-link {
     display: flex;
-    flex-direction: column;
-    gap: 0.125rem;
-    padding: 0.5rem 0.625rem;
+    align-items: flex-start;
+    /* The input's own gap between its glyph and its text. */
+    gap: 0.5rem;
+    /* The list pays `0.375rem` around this, so `0.75rem` here lands the icon
+     * on the dialog's 18px column. See the footer, which is the anchor. */
+    padding: 0.5rem 0.75rem;
     border-radius: var(--wave-docs-radius-sm);
     color: var(--wave-docs-fg);
     text-decoration: none;
   }
 
+  .wave-docs-search-result-icon {
+    flex: none;
+    /*
+     * ⚠️ NUDGED DOWN, NOT CENTRED. `align-items: center` would centre this on
+     * the *two-line* block, so it would sit between the heading and the route
+     * rather than beside the heading — and it would move when a route wrapped.
+     * A 1rem glyph on a 0.9375rem/1.4 line is 5px shorter than the line box, so
+     * half of that puts it on the heading's optical centre and keeps it there.
+     */
+    margin-block-start: 0.15625rem;
+    color: var(--wave-docs-fg-subtle);
+  }
+
+  .wave-docs-search-result-text {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+    /* So a long heading ellipsises inside the row rather than widening it. */
+    min-width: 0;
+  }
+
+  /*
+   * The separator between two route segments — the package's own chevron
+   * rather than a character, so there is no font for it to be missing from.
+   *
+   * The `viewBox` is cropped to the painted ink, so the box is the glyph: it
+   * sits on the baseline the way a letter does, with no alignment to correct.
+   */
+  .wave-docs-search-result-sep {
+    height: 7px;
+    width: auto;
+    /*
+     * The `viewBox` is exactly the stroke's extent, so the tip lands on the
+     * box's own edge and an SVG clips at that edge by default — the point came
+     * out flat. Nothing here overlaps: what spills is a fraction of a pixel of
+     * anti-aliasing.
+     */
+    overflow: visible;
+    /* The air either side. */
+    margin-inline: 4px;
+    color: var(--wave-docs-fg-subtle);
+  }
+
   .wave-docs-search-result-heading {
     font-size: 0.9375rem;
     font-weight: 600;
@@ -4133,10 +4540,21 @@
     white-space: nowrap;
     text-overflow: ellipsis;
     color: var(--wave-docs-fg-subtle);
-    font-family: var(--wave-docs-font-mono);
-    /* Smaller than the trail was: a monospace face reads larger at the same
-     * size, and this line is a reference rather than something to read. */
-    font-size: 0.6875rem;
+    /*
+     * The package's sans, the same face as everything else in the dialog.
+     *
+     * ⚠️ IT WAS MONOSPACE, AND THAT IS WHAT MADE THE SEPARATOR UNRELIABLE. A
+     * mono face advances every glyph one cell, so the trail sat on a rigid
+     * grid an icon could not join, and its metrics are whatever the machine
+     * resolves — SF Mono here, Consolas on Windows, Liberation Mono on Linux —
+     * so the cap height the chevron is sized against moved from reader to
+     * reader. Set in the sans, the line has ordinary proportional spacing and
+     * one set of metrics to match.
+     */
+    font-family: var(--wave-docs-font-sans);
+    /* A notch up from the mono's `0.6875rem`: a monospace face reads larger at
+     * the same size, so holding the number would have shrunk this line. */
+    font-size: 0.75rem;
     line-height: 1.5;
   }
 

package/package.json

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