@waveso/docs 0.10.0 → 0.12.0

package/dist/styles.css

@@ -142,8 +142,51 @@
      * no shadow, so the dark ramp deepens it rather than reusing it. */
     --wave-docs-shadow: oklch(0 0 0 / 0.3);
 
-    --wave-docs-radius: 0.5rem;
-    --wave-docs-radius-sm: 0.375rem;
+    /*
+     * ⚠️ ONE ROOT AND THREE TIERS, DERIVED — AND THE NUMBERS ARE `@waveso/ui`'s.
+     *
+     * A site running both this package and the component library should not
+     * have two radius scales a few pixels apart, and the way to guarantee that
+     * is to take theirs rather than to keep ours in step by hand. `--radius`
+     * there is `0.625rem` with `--radius-sm/md/lg` at `calc(root ∓ --spacing)`;
+     * this is the same construction with the step written out, because
+     * `--spacing` is Tailwind's and this package does not depend on Tailwind.
+     *
+     * ⚠️ AND THE ROOT IS THE OVERRIDE POINT, WHICH IS THE WHOLE REASON IT
+     * EXISTS. A host already running `@waveso/ui` writes one line —
+     * `--wave-docs-radius-base: var(--radius)` — and the docs follow their
+     * app's corners, including any theme that moves them. Overriding three
+     * tokens separately is three chances to break the concentric arithmetic
+     * below.
+     *
+     * Which tier a box takes is decided by what *kind* of box it is, never by
+     * how big it happens to be:
+     *
+     *   `-sm`   inline chips, small controls, and focus rings drawn on those
+     *   base    controls, overlays, and the panel's inset surface
+     *   `-lg`   every block in the reading flow, and the panel's outer edge
+     *
+     * ⚠️ THE BLOCK TIER WAS SPLIT BEFORE THIS. Callouts, images and video
+     * embeds sat at the base radius while a code frame and a table sat at 19px,
+     * so two blocks a paragraph apart disagreed by eleven pixels. 19 was
+     * measured off a reference site, which is a fine way to pick a number and a
+     * bad way to pick a system.
+     */
+    --wave-docs-radius-base: 0.625rem;
+    /*
+     * The step between tiers, and the panel's padding is the same number
+     * *by construction* below rather than by coincidence: the panel's inset
+     * surface has to be its frame's radius minus its own padding, or the two
+     * corners run at different curvatures.
+     */
+    --wave-docs-radius-step: 0.25rem;
+    --wave-docs-radius-sm: calc(
+      var(--wave-docs-radius-base) - var(--wave-docs-radius-step)
+    );
+    --wave-docs-radius: var(--wave-docs-radius-base);
+    --wave-docs-radius-lg: calc(
+      var(--wave-docs-radius-base) + var(--wave-docs-radius-step)
+    );
     /* The shell. These five plus `--wave-docs-measure` are the whole settable
      * layout surface; the gutter and the drawer width are literals, because each
      * appears once and an ordinary override is already the cleanest tool for
@@ -217,6 +260,25 @@
   }
 
   /* Only for a host that has explicitly delegated the choice to the OS. */
+  /*
+   * ⚠️ A SQUIRCLE READS TIGHTER THAN A CIRCULAR ARC AT THE SAME RADIUS, so
+   * where `corner-shape` is live the root moves up to restore the roundness
+   * the numbers were chosen for. `@waveso/ui` does the same, to the same
+   * value, and the two have to agree or a page running both shows two
+   * different corners on the same screen.
+   *
+   * Only the root moves. Every tier is a `calc()` off it and the panel's
+   * padding is the step, so the concentric arithmetic survives untouched — and
+   * a browser without squircles keeps the original scale rather than a scale
+   * tuned for a shape it cannot draw.
+   */
+  @supports (corner-shape: squircle) {
+    :root {
+      --wave-docs-radius-base: 1rem;
+    }
+  }
+
+
   @media (prefers-color-scheme: dark) {
     :root[data-theme='system'] {
       color-scheme: dark;
@@ -394,6 +456,7 @@
   .wave-docs-toc,
   .wave-docs-skip-link,
   .wave-docs-hero,
+  .wave-docs-explore,
   .wave-docs-pager,
   .wave-docs-layout__sidebar,
   .wave-docs-search-trigger,
@@ -659,11 +722,27 @@
     accent-color: var(--wave-docs-accent);
   }
 
+  /*
+   * ⚠️ A FULL BORDER, AND IT WAS A 3px RULE DOWN THE INLINE START.
+   *
+   * A quote is a block set apart from the prose, and every other block set
+   * apart from the prose here — a callout, a code frame, a table, an embed —
+   * is a box. A single edge made it the one exception, and next to a callout
+   * two paragraphs away it read as a different kind of thing rather than as a
+   * quieter one.
+   *
+   * The same box as `.wave-docs-callout`, minus the hue: same padding, same
+   * block radius, a plain border instead of a tinted one and no accent edge.
+   * That is the relationship — a callout is a quote with a colour, and now it
+   * looks like one.
+   */
   .wave-docs-prose blockquote {
-    padding-inline-start: 1rem;
-    border-inline-start: 3px solid var(--wave-docs-border-strong);
+    /* The callout's padding, so the two line their text up with each other. */
+    padding: 0.875rem 1rem;
+    border: 1px solid var(--wave-docs-border);
+    border-radius: var(--wave-docs-radius-lg);
     color: var(--wave-docs-fg-muted);
-    /* Not italic. The rule and the muted colour already say "quotation"; a
+    /* Not italic. The box and the muted colour already say "quotation"; a
      * long italic passage is measurably slower to read, and markdown authors
      * use blockquotes for asides and notes, not only for speech. */
     font-style: normal;
@@ -693,7 +772,7 @@
   .wave-docs-image {
     max-width: 100%;
     height: auto;
-    border-radius: var(--wave-docs-radius);
+    border-radius: var(--wave-docs-radius-lg);
   }
 
   /* Inline code only. `.shiki` owns everything inside a `<pre>`. */
@@ -709,6 +788,49 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * Squircle corners
+ *
+ * `corner-shape` draws every `border-radius` as a continuous superellipse
+ * rather than a circular arc — softer, and what `@waveso/ui` renders — and
+ * degrades to ordinary rounding where it is unsupported. Chrome has it today;
+ * Safari and Firefox do not, so this is an enhancement and never a dependency.
+ * ------------------------------------------------------------------------ */
+
+@layer components {
+  @supports (corner-shape: squircle) {
+    /*
+     * ⚠️ SCOPED TO ELEMENTS THIS PACKAGE OWNS, AND NOT `*`.
+     *
+     * `@waveso/ui` can say `*` because it is the application's own stylesheet.
+     * This one is mounted inside somebody else's page, and a bare `*` would
+     * reshape every corner the host drew — the same class of trespass as
+     * claiming `html` or `body`, which this file already refuses.
+     *
+     * The attribute pair matches our classes wherever they sit in a class
+     * list. The prose elements are named separately because they are the
+     * markdown author's tags rather than ours: an inline `<code>` chip, a
+     * `<kbd>`, an excluded `<pre>`. They are rounded by rules scoped to
+     * `.wave-docs-prose`, so they are ours to shape.
+     */
+    :is([class^='wave-docs-'], [class*=' wave-docs-']),
+    .wave-docs-prose :is(blockquote, code, kbd, pre) {
+      corner-shape: squircle;
+    }
+
+    /*
+     * ⚠️ PILLS AND DOTS OPT BACK OUT. A squircle at `9999px` is a lozenge with
+     * flattened ends rather than a pill, and a squircled dot is a rounded
+     * square. Both are pseudo-elements, which `[class]` selectors cannot
+     * reach, so they are named.
+     */
+    .wave-docs-layout__sidebar-trigger::before,
+    .wave-docs-layout__sidebar-trigger::after {
+      corner-shape: round;
+    }
+  }
+}
+
 /* ---------------------------------------------------------------------------
  * Tables
  * ------------------------------------------------------------------------ */
@@ -744,7 +866,21 @@
     grid-template-columns: minmax(max-content, 1fr);
     overflow-x: auto;
     border: 1px solid var(--wave-docs-border);
-    border-radius: var(--wave-docs-radius);
+    /*
+     * ⚠️ THE PANEL'S OUTER RADIUS ON A BOX THAT IS NOT A PANEL, AND THAT IS
+     * DELIBERATE.
+     *
+     * A table wore `.wave-docs-panel` for a while — frame, band, inset card.
+     * The panel exists to separate *chrome* from *content*, and a table's
+     * header row is content: setting the body into a card away from its own
+     * header cost three vertical rules down each side, stopped the dividers
+     * short of the box and narrowed the reading width, on the densest element
+     * on a page. Full-width dividers are what let an eye track a row across.
+     *
+     * The radius is what is kept, so a table and a code block still read as two
+     * of one family without the table pretending to chrome it has not got.
+     */
+    border-radius: var(--wave-docs-radius-lg);
     scrollbar-width: thin;
     scrollbar-color: var(--wave-docs-border-strong) transparent;
     /*
@@ -777,8 +913,21 @@
         right / 0.75rem 100% no-repeat scroll;
   }
 
+  /*
+   * A table wears the panel: the outer frame, and its scroll region as the
+   * inset surface. There is no header row — a GFM table has no caption to put
+   * in one — so this is the frame alone, which is the point. It is what makes
+   * a table, a code block and "where to go next" read as three of one thing
+   * rather than three boxes that happen to be near each other.
+   */
   .wave-docs-table-scroll:focus-visible {
     outline: 2px solid var(--wave-docs-accent);
+    /*
+     * Positive, unlike the `<pre>`'s. This element *is* the scroll container,
+     * and an element's own overflow does not clip its own outline — so the ring
+     * draws into the frame's 4px band around it, which is exactly where there
+     * is room for it.
+     */
     outline-offset: 2px;
   }
 
@@ -999,6 +1148,24 @@
     white-space: nowrap;
   }
 
+  /*
+   * ⚠️ AN EMPTY HEADER ROW DRAWS NO BAND, AND GFM PRODUCES ONE ROUTINELY.
+   *
+   * A GFM table *always* has a `<thead>` — the delimiter row is what makes it a
+   * table at all — so an author who wants a plain two-column list of facts
+   * writes `| | |` and gets a header of empty `<th>`s. With the card starting
+   * at the body, that painted a bare strip of the frame's ground above it with
+   * nothing in it: a panel with an empty header, which reads as a rendering
+   * fault rather than as a table without column names.
+   *
+   * `:empty` and not a text check: GFM emits `<th></th>` for a blank cell, with
+   * no whitespace inside it. A header with even one named column keeps its
+   * band, which is the case the band exists for.
+   */
+  .wave-docs-table thead:not(:has(th:not(:empty))) {
+    display: none;
+  }
+
   /*
    * ⚠️ `tbody tr + tr` ONLY. `thead` WAS IN THIS SELECTOR AND DOUBLED THE FRAME.
    *
@@ -1008,9 +1175,9 @@
    * `--wave-docs-border` instead of one, which reads as a thick or doubled
    * line rather than as a frame.
    *
-   * The header's separator is the one below it, and that is drawn by the
-   * `inset 0 -1px 0` box-shadow on `thead th` — a shadow rather than a border
-   * so it survives the cell being `position: sticky`.
+   * The header's separator is the one below it, drawn by the `inset 0 -1px 0`
+   * box-shadow on `thead th` — a shadow rather than a border so it survives
+   * the cell being `position: sticky`.
    */
   .wave-docs-table tbody tr + tr {
     border-block-start: 1px solid var(--wave-docs-border);
@@ -1076,12 +1243,37 @@
    * ---------------------------------------------------------------------- */
 
   .wave-docs-code {
-    position: relative;
     /*
-     * ⚠️ `margin-inline`, NOT `margin`. The `<pre>` inside carries the border
-     * and the background; this figure is only a positioning context, and a
-     * default `<figure>` margin would indent the whole block by 40px — which is
-     * what this rule was written for.
+     * ⚠️ A GRID ON THE FIGURE ITSELF, NOT A `.wave-docs-panel__header` WRAPPER.
+     *
+     * A `<figcaption>` has to be a direct child of its `<figure>`. Wrapped in
+     * the header `<div>` "where to go next" uses, it captions nothing: the
+     * markup is invalid and a titled block loses the accessible name it had.
+     * So the frame wears `.wave-docs-panel`, its surface wears
+     * `.wave-docs-panel__body`, and the header row is laid out here — sharing
+     * the primitive's insets rather than its header element.
+     *
+     * ⚠️ AND THE FIRST ROW IS FLOORED RATHER THAN LEFT TO ITS CONTENT. With a
+     * label it is the label's height; with none it is the copy button's, and
+     * those differ by 4px — enough that a page mixing titled and untitled
+     * fences shows two header heights and reads as a rendering bug.
+     */
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-rows: minmax(var(--wave-docs-panel-header-row), auto) auto;
+    align-items: center;
+    /*
+     * The code's own ground rather than the panel's default. A code block is
+     * part of the surface ramp and a reader expects it darker than the page;
+     * the panel paints `--wave-docs-bg` for a widget made of prose, which is
+     * the right default and the wrong one here. Set on the frame so it reaches
+     * the surface by inheritance — see the property's note on the panel.
+     */
+    --wave-docs-panel-surface: var(--wave-docs-code-block-bg);
+    /*
+     * ⚠️ `margin-inline`, NOT `margin`. A default `<figure>` margin would
+     * indent the whole block by 40px — which is what this rule was written
+     * for.
      *
      * Zeroing all four also took the *block* margin, and `.wave-docs-prose > *
      * + *` is the same specificity and declared earlier, so this won. Every
@@ -1092,68 +1284,113 @@
     margin-inline: 0;
   }
 
-  .wave-docs-code__title {
-    display: flex;
-    align-items: center;
-    /* Room for the button, which is absolutely positioned over this row. */
-    padding: 0.5rem 3rem 0.5rem 1.125rem;
-    border: 1px solid var(--wave-docs-border);
-    border-block-end: 0;
-    border-start-start-radius: var(--wave-docs-radius);
-    border-start-end-radius: var(--wave-docs-radius);
-    background-color: var(--wave-docs-bg-subtle);
-    color: var(--wave-docs-fg-muted);
-    font-family: var(--wave-docs-font-mono);
-    font-size: 0.8125rem;
-  }
-
-  /* Square off the top of a `<pre>` that sits under a title bar.
-   *
-   * `.wave-docs-prose` first, even though `.wave-docs-code` is our class and
-   * only ever appears inside it: `styles.test.ts` requires every `.shiki` rule
-   * to name the prose scope, so the package can never style a code block it
-   * did not render. One form for that invariant is worth the extra selector. */
   /*
-   * ⚠️ THE `<pre>`'s USER-AGENT MARGIN, WHICH UNDID THE FRAME.
+   * ⚠️ AN UNTITLED FENCE HAS NO FRAME AT ALL, AND THAT IS THE WHOLE RULE.
    *
-   * A `<pre>` defaults to `margin-block: 1em`, and at this block's 0.875rem
-   * that is 14px — measured in Chromium on the real site, not reasoned about.
-   * So the title bar dropped its bottom border and squared its bottom corners
-   * to join the code below it, and then the browser pushed the two 14px apart:
-   * a caption floating over a gap, which is the one arrangement the frame was
-   * designed not to be.
+   * With a title the figure is a panel: a band carrying the filename and the
+   * copy button, and the code set into a card below it. With none there is
+   * nothing to put in a band — so the frame flattens away, the surface becomes
+   * the block, and the button sits on the code.
    *
-   * It mis-seated the copy button too. The button is positioned against the
-   * `<figure>`, so on a fence with no title the margin slid the code down out
-   * from under it.
+   * The language does not count as a title. A fence that declares `ts` and no
+   * filename is still an untitled fence, and a band holding a two-letter badge
+   * is the empty-header problem with a word in it. `data-lang` stays on the
+   * figure for anyone selecting on it.
    *
-   * Invisible to every test here before the site existed: jsdom has no layout,
-   * and `styles.test.ts` reads rules as text. It took a screenshot of a real
-   * page to see it.
+   * One shape of markup, switched here rather than in the pipeline: two markup
+   * paths mean two fixtures, and the one that is not on screen is the one that
+   * rots.
    */
-  .wave-docs-prose .wave-docs-code .shiki {
-    margin: 0;
+  .wave-docs-code:not(:has(.wave-docs-code__title)) {
+    /* The containing block for the button below. The grid has one child left
+     * in flow, so it has nothing to lay out. */
+    position: relative;
+    display: block;
+    padding: 0;
+    border: 0;
+    background: transparent;
   }
 
-  .wave-docs-prose .wave-docs-code:has(.wave-docs-code__title) .shiki {
-    border-start-start-radius: 0;
-    border-start-end-radius: 0;
+  .wave-docs-code:not(:has(.wave-docs-code__title)) .wave-docs-code__body {
+    /* It is the outer box now, so it takes the outer radius. Leaving it at the
+     * card's would round an unframed block more tightly than a framed one. */
+    border-radius: var(--wave-docs-radius-lg);
   }
 
-  .wave-docs-code__copy {
+  .wave-docs-code:not(:has(.wave-docs-code__title)) .wave-docs-code__copy {
+    /*
+     * On the code rather than beside it. `z-index` because the `<pre>` is a
+     * scroll container and paints its own content above a static sibling; the
+     * button would otherwise disappear under a wide line rather than over it.
+     */
     position: absolute;
-    top: 0.5rem;
-    inset-inline-end: 0.5rem;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
+    z-index: 1;
+    inset-block-start: 0.375rem;
+    inset-inline-end: 0.375rem;
+    margin-inline-end: 0;
+  }
+
+  /*
+   * The label slot: the fence's `title="…"`, which is the only thing that goes
+   * in it.
+ One or the other and never both — `swap.ts` beside a `ts` badge
+   * is the same fact twice, and the filename is the more precise half.
+   */
+  .wave-docs-code__title {
+    grid-row: 1;
+    grid-column: 1;
+    /* The track is `minmax(0, 1fr)` so a long path can shrink it; these two let
+     * the path wrap inside that track instead of pushing the button out of the
+     * frame. */
+    min-width: 0;
+    overflow-wrap: anywhere;
+    /*
+     * ⚠️ THE `+ 1px` IS THE SURFACE'S BORDER, AND IT IS THE SAME SUBTRACTION
+     * `.wave-docs-panel__header` MAKES — the reason the inset is exported at
+     * all. The label's first character and the code's first character sit on
+     * one column; without it they miss by exactly one border, which appears in
+     * no rule and reads as a design decision.
+     */
+    padding-inline-start: calc(var(--wave-docs-panel-inset) + 1px);
+    color: var(--wave-docs-fg-muted);
+    font-family: var(--wave-docs-font-mono);
+    font-size: 0.8125rem;
+  }
+
+  .wave-docs-code__body {
+    grid-column: 1 / -1;
+  }
+
+  .wave-docs-code__copy {
+    grid-row: 1;
+    grid-column: 2;
+    /*
+     * Optically inset, not aligned to the label's column: a 2rem hit target
+     * held 17px off the frame's edge reads as floating in the middle of the
+     * row rather than as the control that ends it.
+     */
+    margin-inline-end: calc(var(--wave-docs-panel-inset) - 0.5rem);
+    /* A grid, so the three state icons stack in one cell. */
+    display: grid;
+    place-items: center;
+    /*
+     * A 2rem hit target around a 1rem glyph. The box stays even though nothing
+     * draws it at rest — a control smaller than the icon plus its padding is a
+     * control people miss on a touch screen.
+     */
     width: 2rem;
     height: 2rem;
-    border: 1px solid var(--wave-docs-border);
+    /*
+     * ⚠️ NO BORDER AND NO GROUND, IN ANY STATE. It had both, and a bordered,
+     * filled 2rem box on the frame's own band is a third framed rectangle
+     * inside a frame that already has two — for a control secondary to
+     * everything around it. The glyph is the whole control; hover moves its
+     * ink, not a box behind it.
+     */
+    border: 0;
     border-radius: var(--wave-docs-radius-sm);
-    background-color: var(--wave-docs-bg);
-    color: var(--wave-docs-fg-muted);
-    font-size: 0.875rem;
+    background-color: transparent;
+    color: var(--wave-docs-fg-subtle);
     cursor: pointer;
     /*
      * ⚠️ HIDDEN UNTIL THE RUNTIME SAYS OTHERWISE, AND THIS IS STRUCTURAL.
@@ -1165,71 +1402,88 @@
      * a control that is invisible, focusable, and does nothing.
      */
     visibility: hidden;
-    opacity: 0;
-    transition: opacity 120ms ease;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .wave-docs-code__copy {
-      transition: none;
-    }
   }
 
   html[data-wave-docs-code-ready] .wave-docs-code__copy {
     visibility: visible;
   }
 
-  .wave-docs-code:hover .wave-docs-code__copy,
-  .wave-docs-code:focus-within .wave-docs-code__copy,
-  /* A title bar already reserves the space, so there is nothing to reveal. */
-  .wave-docs-code:has(.wave-docs-code__title) .wave-docs-code__copy {
-    opacity: 1;
-    /*
-     * ⚠️ CENTRED IN THE TITLE BAR, NOT INSET FROM THE FIGURE.
-     *
-     * The button is positioned against the `<figure>`, which is the whole code
-     * block, so a single `top` cannot be right for both shapes. Against a bare
-     * fence, `0.5rem` insets it from the top of the `<pre>`, which is correct.
-     * Against a title bar it measured 8px of space above and **0 below** — the
-     * button sitting flush on the bar's own border, which reads as misaligned
-     * rather than as inset.
-     *
-     * The bar is 40px and the button is 32px, so 4px is the centre. A `top:
-     * 50%` would be wrong here: the percentage resolves against the figure,
-     * which includes the code block below.
-     */
-    top: 0.25rem;
-  }
+  /*
+   * ⚠️ NO HOVER REVEAL, AND ITS ABSENCE IS THE POINT.
+   *
+   * The button used to fade in on `:hover` or `:focus-within`, because it was
+   * absolutely positioned over the code and had nowhere of its own to be. It
+   * has a slot in the header row now, and a reserved slot that is empty until
+   * you point at it reads as a rendering fault rather than as restraint — so
+   * the reveal, the `@media (hover: none)` exception that existed because a
+   * hover-only control does not exist on a phone, and the reduced-motion guard
+   * on its transition all went with it.
+   */
+
 
   /*
-   * A control that only appears on hover does not exist on a phone. This is
-   * the whole of the mobile story for copy, and it is one query.
+   * ⚠️ INK ONLY — NO GROUND ON HOVER EITHER. The accent is the same signal
+   * every other interactive surface in this package gives, and it needs no box
+   * behind it to be read. A ground here also had nowhere to come from: the
+   * subtle ramp *is* the frame's colour, so the hover state this used to have
+   * was the colour the button was already sitting on.
    */
-  @media (hover: none) {
-    .wave-docs-code__copy {
-      opacity: 1;
-    }
+  .wave-docs-code__copy:hover {
+    color: var(--wave-docs-accent);
   }
 
-  .wave-docs-code__copy:hover {
-    background-color: var(--wave-docs-bg-subtle);
-    color: var(--wave-docs-fg);
+  /*
+   * ⚠️ AND IT HAD NO FOCUS RULE AT ALL, WHICH THE BORDER WAS QUIETLY COVERING
+   * FOR.
+   *
+   * A 1px box around a control is not a focus indicator — it is there whether
+   * the control is focused or not — so a keyboard reader tabbing onto this
+   * button got a `color` change and nothing else, and the package's own
+   * inventory of focusable surfaces did not list it. Taking the border away
+   * makes that visible; it does not create it.
+   */
+  .wave-docs-code__copy:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: 2px;
   }
 
   /* The success state, swapped by CSS rather than by React: no component owns
    * a button, so there is no state to re-render and nothing to hydrate. */
+  /*
+   * ⚠️ ONE OF THREE ICONS, SWAPPED BY `display` AND NOT BY `visibility`.
+   *
+   * All three ship in the markup — no component owns this button, so there is
+   * no state to re-render and nothing to hydrate; the runtime writes one
+   * attribute and the stylesheet picks.
+   *
+   * `visibility` is the wrong property here and would have been a real defect:
+   * the button is `visibility: hidden` until the runtime attaches, and
+   * `visibility` inherits, so a child setting it back to `visible` shows an
+   * icon inside a button that is meant to be invisible and out of the tab
+   * order. `display` does not inherit, so the button's own rule still wins.
+   */
+  .wave-docs-code__copy-icon {
+    /* Stacked in one cell, so the button does not resize as the state
+     * changes and the glyph does not shift by a pixel between them. */
+    grid-area: 1 / 1;
+  }
+
+  .wave-docs-code__copy-icon:not([data-state='idle']) {
+    display: none;
+  }
+
+  /* The success state, swapped by CSS rather than by React. */
   .wave-docs-code__copy[data-copied='true'] {
-    border-color: var(--wave-docs-callout-tip);
     color: var(--wave-docs-callout-tip);
   }
 
-  .wave-docs-code__copy[data-copied='true'] > * {
-    visibility: hidden;
+  .wave-docs-code__copy[data-copied='true'] .wave-docs-code__copy-icon {
+    display: none;
   }
 
-  .wave-docs-code__copy[data-copied='true']::after {
-    content: '\2713';
-    position: absolute;
+  .wave-docs-code__copy[data-copied='true']
+    .wave-docs-code__copy-icon[data-state='copied'] {
+    display: block;
   }
 
   /*
@@ -1242,21 +1496,21 @@
    * phone over `http://192.168.x.x:3000` is not a secure context, so
    * `navigator.clipboard` is undefined and no amount of pressing helps. A
    * silent no-op is the worst possible answer to that.
+   *
+   * A cross, not a warning triangle: it pairs with the tick at the same
+   * stroke weight, and the triangle reads as a page-level alert.
    */
   .wave-docs-code__copy[data-copied='false'] {
-    border-color: var(--wave-docs-callout-caution);
     color: var(--wave-docs-callout-caution);
   }
 
-  .wave-docs-code__copy[data-copied='false'] > * {
-    visibility: hidden;
+  .wave-docs-code__copy[data-copied='false'] .wave-docs-code__copy-icon {
+    display: none;
   }
 
-  .wave-docs-code__copy[data-copied='false']::after {
-    /* A cross, not a warning triangle: it pairs with the tick above at the
-     * same weight, and the triangle reads as a page-level alert. */
-    content: '\00d7';
-    position: absolute;
+  .wave-docs-code__copy[data-copied='false']
+    .wave-docs-code__copy-icon[data-state='failed'] {
+    display: block;
   }
 
   /*
@@ -1287,7 +1541,7 @@
   .wave-docs-prose pre:not(.shiki) {
     padding: 1rem 1.125rem;
     border: 1px solid var(--wave-docs-border);
-    border-radius: var(--wave-docs-radius);
+    border-radius: var(--wave-docs-radius-lg);
     background-color: var(--wave-docs-code-block-bg);
     overflow-x: auto;
     font-family: var(--wave-docs-font-mono);
@@ -1297,13 +1551,37 @@
   }
 
   .wave-docs-prose .shiki {
-    padding: 1rem 1.125rem;
-    border: 1px solid var(--wave-docs-border);
-    border-radius: var(--wave-docs-radius);
-    /* Our token, not `--shiki-light-bg`: the code block is part of the page's
-     * surface ramp, and a theme's own background is whatever GitHub chose. */
-    background-color: var(--wave-docs-code-block-bg);
+    /*
+     * ⚠️ NO BORDER, NO RADIUS AND NO BACKGROUND OF ITS OWN — THE PANEL'S
+     * SURFACE CARRIES ALL THREE NOW. `rehypeCodeFrame` puts every highlighted
+     * fence inside a `.wave-docs-panel__body`, so declaring them here draws a
+     * second frame one pixel inside the first. `pre:not(.shiki)` above keeps
+     * its own, because an excluded fence is never wrapped.
+     *
+     * ⚠️ AND THE INLINE PADDING IS `1rem` BECAUSE THAT IS
+     * `--wave-docs-panel-inset`, NOT BECAUSE IT IS A ROUND NUMBER. The frame's
+     * label sits at that inset plus the surface's border; the first character
+     * of the code sits at the surface's border plus this. Equal, they land on
+     * one column. The `1.125rem` this was put the code 2px right of the
+     * filename above it — visible, and attributable to nothing.
+     */
+    padding: 1rem;
+    /*
+     * ⚠️ THE `<pre>` SCROLLS AND THE SURFACE AROUND IT CLIPS, WHICH IS WHY
+     * THEY ARE TWO BOXES. One box cannot both round its corners with
+     * `overflow: hidden` and scroll a wide line: the first value wins and the
+     * line is cut off with no way to reach it.
+     */
     overflow-x: auto;
+    /*
+     * ⚠️ THE `<pre>`'s USER-AGENT MARGIN, WHICH UNDOES THE FRAME.
+     *
+     * A `<pre>` defaults to `margin-block: 1em`, and at this block's 0.875rem
+     * that is 14px — measured in Chromium on the real site, not reasoned
+     * about. Left in, it pushes the code away from the surface holding it and
+     * the frame reads as a caption floating over a gap.
+     */
+    margin: 0;
     font-family: var(--wave-docs-font-mono);
     font-size: 0.875rem;
     line-height: 1.7;
@@ -1320,7 +1598,17 @@
    * had no focus style. */
   .wave-docs-prose .shiki:focus-visible {
     outline: 2px solid var(--wave-docs-accent);
-    outline-offset: 2px;
+    /*
+     * ⚠️ NEGATIVE, BECAUSE THE SURFACE AROUND THIS ONE CLIPS.
+     *
+     * The `<pre>` fills `.wave-docs-panel__body`, which is `overflow: hidden`
+     * so a square corner cannot poke through the frame's rounded one. An
+     * outline drawn *outside* the `<pre>`'s border box is outside the
+     * surface's content box as well, so the `2px` this was got clipped away
+     * to nothing and the one focusable element in a code block had a focus
+     * style that could not be seen. Inset, it lands on the code's own edge.
+     */
+    outline-offset: -2px;
   }
 
   .wave-docs-prose .shiki code {
@@ -1357,9 +1645,22 @@
     --callout-bg: var(--wave-docs-callout-note-bg);
 
     padding: 0.875rem 1rem;
+    /*
+     * ⚠️ ONE UNIFORM EDGE, AND THERE WAS A 3px ACCENT DOWN THE INLINE START.
+     *
+     * Every other block set apart from the prose here is a box with one border
+     * all the way round; the accent edge made a callout the exception, and a
+     * thick rule on one side of a squircled box also fights the corner it runs
+     * into. A blockquote is this box without the hue, which is the relationship
+     * — and a stripe on one of them broke it.
+     *
+     * ⚠️ AND THE TYPE IS STILL NOT CONVEYED BY COLOUR ALONE. The stripe was
+     * never what carried it: the icon and the label — "Note", "Warning" — are
+     * the non-colour signals, and they are unchanged. The tinted border and
+     * ground remain as reinforcement rather than as the whole message.
+     */
     border: 1px solid color-mix(in oklab, var(--callout-accent) 35%, transparent);
-    border-inline-start: 3px solid var(--callout-accent);
-    border-radius: var(--wave-docs-radius);
+    border-radius: var(--wave-docs-radius-lg);
     background: var(--callout-bg);
   }
 
@@ -1412,7 +1713,7 @@
     position: relative;
     aspect-ratio: 16 / 9;
     overflow: hidden;
-    border-radius: var(--wave-docs-radius);
+    border-radius: var(--wave-docs-radius-lg);
     background: oklch(0 0 0);
   }
 
@@ -1872,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;
@@ -1888,6 +2198,247 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * Panel
+ *
+ * A framed block with a header and an inset surface: the outer card names the
+ * thing and carries its controls, the inner one holds the content.
+ *
+ * Its own section because it is not one component's furniture — "where to go
+ * next" is the first thing to wear it and a code frame is the next, and two
+ * copies of the same three rules is how they drift apart.
+ * ------------------------------------------------------------------------ */
+
+@layer components {
+  /*
+   * ⚠️ THE TWO RADII ARE NOT INDEPENDENT NUMBERS. A rounded box inside a
+   * rounded box only looks right when the inner radius is the outer one minus
+   * the gap between them — otherwise the corners run at different curvatures
+   * and the inner box reads as *pasted onto* the frame rather than set into it.
+   *
+   * The tokens are chosen so that arithmetic lands on one of them: `1rem` outer
+   * minus `0.5rem` of padding is `0.5rem`, which is `--wave-docs-radius`. Change
+   * the padding and the body's radius has to move with it.
+   */
+  .wave-docs-panel {
+    /*
+     * ⚠️ THE STEP, NOT A LITERAL `4px` THAT HAPPENS TO MATCH IT. The inset
+     * surface below takes the base radius and this frame takes `-lg`, which is
+     * the base plus one step — so the surface's corner is concentric with the
+     * frame's only while this padding *is* that step. Written as the token, a
+     * host moving `--wave-docs-radius-base` keeps both true; written as `4px`,
+     * the two drift the first time anyone retunes the scale.
+     */
+    padding: var(--wave-docs-radius-step);
+    border: 1px solid var(--wave-docs-border);
+    border-radius: var(--wave-docs-radius-lg);
+    background: var(--wave-docs-bg-subtle);
+    /*
+     * ⚠️ THE INSET THE BODY'S CONTENT USES, AND IT IS NOT THE SAME NUMBER AS
+     * THE HEADER'S. The title sits at the frame's padding; anything inside the
+     * body sits at the frame's padding *plus the body's own border*, so the two
+     * columns miss each other by a pixel per border. Measured before this: the
+     * rows of "where to go next" started 9px right of the heading above them —
+     * a number that appears in no rule, and looks like a design decision.
+     *
+     * Exported rather than repeated, because the next component to wear the
+     * panel has to make the same subtraction and will not think to — and the
+     * correction is applied to the *header* below rather than baked in here, so
+     * a component wearing the panel writes the clean value and the panel keeps
+     * its own arithmetic to itself.
+     */
+    --wave-docs-panel-inset: 1rem;
+    /*
+     * The header row's floor, exported for the same reason the inset is: the
+     * code frame lays its header out on a grid rather than in
+     * `.wave-docs-panel__header`, because a `<figcaption>` cannot live inside a
+     * wrapper, and two components drawing the same row to two different heights
+     * is how a primitive stops being one.
+     */
+    --wave-docs-panel-header-row: 2.25rem;
+    /*
+     * The surface's ground is a property a wearer sets on the frame — see the
+     * `var()` fallback on `__body`, which is where its default lives.
+     */
+  }
+
+  /*
+   * The header lives in the frame's padding rather than in a band of its own:
+   * the inset surface below is what draws the line between them, so a border
+   * here would be a second one.
+   */
+  .wave-docs-panel__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    /*
+     * ⚠️ THE `+ 1px` IS THE BODY'S BORDER, AND IT IS WHAT PUTS THE TITLE ON THE
+     * SAME COLUMN AS THE CONTENT BELOW IT. The title's box starts at the
+     * frame's padding; the body's content starts at that padding plus the
+     * body's own border, so equal insets miss each other by exactly one border.
+     * Derived rather than written out, so moving `--wave-docs-panel-inset`
+     * moves both.
+     */
+    min-height: var(--wave-docs-panel-header-row);
+    padding-block: 0.5rem;
+    padding-inline: calc(var(--wave-docs-panel-inset) + 1px);
+  }
+
+  .wave-docs-panel__title {
+    margin: 0;
+    min-width: 0;
+    color: var(--wave-docs-fg);
+    /*
+     * ⚠️ THE TABLE HEADER'S SIZE, DELIBERATELY — they are the same kind of
+     * thing and a page shows both. This and a `<th>` are the label a reader's
+     * eye lands on before the content under it, and 14px against the table's
+     * 15px read as two different levels rather than as one. `styles.test.ts`
+     * pins the pair, because two literals that have to agree are two literals
+     * that drift.
+     *
+     * The weight does not follow. A panel title names the block; a column
+     * header names a column inside one, so the title sits one step heavier.
+     */
+    font-size: 0.9375rem;
+    font-weight: 650;
+    letter-spacing: -0.005em;
+  }
+
+  /* Whatever the header's right-hand controls turn out to be — a copy button, a
+   * language switcher — they are quiet next to the title. */
+  .wave-docs-panel__actions {
+    flex: none;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--wave-docs-fg-subtle);
+    font-size: 0.8125rem;
+  }
+
+  .wave-docs-panel__body {
+    /* See the radius note above: outer minus this box's inset. */
+    border: 1px solid var(--wave-docs-border);
+    /* The frame minus its padding: 12 - 4 = 8, which is the base radius. See
+     * the token block for why that is one number and not two. */
+    border-radius: var(--wave-docs-radius);
+    /*
+     * ⚠️ THE DEFAULT LIVES IN THE FALLBACK, NOT IN A DECLARATION ON
+     * `.wave-docs-panel` — AND THAT IS THE WHOLE FIX, TWICE OVER.
+     *
+     * First: `.wave-docs-code__body` and `.wave-docs-panel__body` are both one
+     * class, so source order decides and the panel is declared later. A code
+     * frame asking for the darker code ground got the panel's white, on the
+     * page, with both rules present and correct.
+     *
+     * Then, with the ground moved to a property: a frame wears
+     * `.wave-docs-panel` *and* `.wave-docs-code`, so both rules set that
+     * property on the same element at the same specificity — and source order
+     * handed it back to the panel. Measured twice as `oklch(1 0 0)` where
+     * `oklch(0.975 0.003 262)` was written.
+     *
+     * In the fallback there is no declaration to lose to: a wearer that sets
+     * the property wins by having set it, and one that does not gets this.
+     */
+    background: var(--wave-docs-panel-surface, var(--wave-docs-bg));
+    /* The frame already clips to its own corners; this keeps a child's square
+     * corner — a `<pre>` — from poking through the inner one. */
+    overflow: hidden;
+  }
+}
+
+/* ---------------------------------------------------------------------------
+ * Where to go next
+ *
+ * A question per row and the page that answers it, from a page's `next`
+ * frontmatter. Emitted by `docs.Page` above the pager.
+ * ------------------------------------------------------------------------ */
+
+@layer components {
+  /*
+   * One block, not a stack of cards. The rows belong to each other — they are
+   * the same question asked seven ways — and seven bordered boxes says seven
+   * unrelated things. One frame with hairlines between reads as a table of
+   * routes, which is what it is.
+   *
+   * The measure and the centring, both: this belongs to the prose, and the
+   * pager below it learned that the hard way.
+   */
+  .wave-docs-explore {
+    max-width: var(--wave-docs-measure);
+    margin-inline: auto;
+    margin-block-start: 3rem;
+  }
+
+  .wave-docs-explore__list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /*
+   * ⚠️ THE RULE IS A TOP BORDER ON EVERY ROW BUT THE FIRST, NOT A BOTTOM ONE ON
+   * EVERY ROW BUT THE LAST. `:last-child` is the wrong hook here: the list is
+   * authored, and a `:last-child` rule leaves a doubled line under the final
+   * row the moment anything is appended to it — including by a consumer's own
+   * CSS. `+` says "between", which is the thing being described.
+   */
+  .wave-docs-explore__item {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 1rem 1.5rem;
+    /* The inline half is the panel's, so a question lines up with the heading
+     * above it — see `--wave-docs-panel-inset`. */
+    padding: 1rem var(--wave-docs-panel-inset);
+  }
+
+  .wave-docs-explore__item + .wave-docs-explore__item {
+    border-block-start: 1px solid var(--wave-docs-border);
+  }
+
+  /*
+   * ⚠️ `min-width: 0` ON THE QUESTION, WHICH IS WHAT LETS IT WRAP. A flex item
+   * floors at its content's min-content width, so a sentence-length question
+   * pushes the answer off the row's inline end instead of taking two lines.
+   */
+  .wave-docs-explore__question {
+    min-width: 0;
+    color: var(--wave-docs-fg-muted);
+  }
+
+  .wave-docs-explore__answer {
+    flex: none;
+    color: var(--wave-docs-accent);
+    font-weight: 600;
+    text-decoration: none;
+  }
+
+  .wave-docs-explore__answer:hover {
+    text-decoration: underline;
+  }
+
+  .wave-docs-explore__answer:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: 2px;
+    border-radius: var(--wave-docs-radius-sm);
+  }
+
+  /*
+   * ⚠️ A CONTAINER QUERY, AND THE CONTAINER IS THE SHELL — the same reasoning
+   * as every other breakpoint in this file. Two columns of sentence-length
+   * questions are cramped in a narrow *box*, which a host can hand us on a
+   * 1920px monitor.
+   */
+  @container wave-docs (max-width: 40rem) {
+    .wave-docs-explore__item {
+      flex-direction: column;
+      align-items: start;
+      gap: 0.25rem;
+    }
+  }
+}
+
 /* ---------------------------------------------------------------------------
  * Pager
  *
@@ -2721,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
@@ -2737,13 +3298,210 @@
     position: sticky;
     top: var(--wave-docs-chrome-offset);
     height: calc(100dvh - var(--wave-docs-chrome-offset));
+    /*
+     * ⚠️ NO `scrollbar-gutter: stable`, AND IT USED TO HAVE ONE.
+     *
+     * It reserved the scrollbar's width whether or not it was showing, so the
+     * column would not jump when the nav grew past a screen. The jump it
+     * prevents is rare and transient; what it cost was permanent and on every
+     * page — measured at 1600px, the nav's content sat 16px from its inline
+     * start and 31px from its end, because the reserved 15px sits *inside* the
+     * padding. A sidebar visibly lopsided on every Windows and Linux machine,
+     * to spare an occasional 15px shift on the same ones.
+     *
+     * It also does nothing where overlay scrollbars are the default — macOS —
+     * so the asymmetry was invisible to anyone who built it.
+     *
+     * `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;
-    /* Reserves the scrollbar's width whether or not it is showing, so the
-     * column does not jump when the nav grows past a screen. */
-    scrollbar-gutter: stable;
+    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. */
@@ -3355,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);
@@ -3415,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;
@@ -3501,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;
   }
 
   /*
@@ -3518,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;
@@ -3575,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;
   }