@waveso/docs 0.9.1 → 0.11.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;
@@ -382,12 +444,20 @@
    * Declared at all because inheriting means a host that never set a family
    * renders its documentation in the UA serif. `--wave-docs-font-sans: inherit`
    * gives the host's typeface back in one line.
+   *
+   * ⚠️ EVERY NEW ROOT HAS TO BE ADDED HERE, AND ONE ALREADY WAS NOT. The pager
+   * sits inside `<main>` but outside `.wave-docs-prose` — `DocContent` owns
+   * that class — so it matched nothing in this list and shipped its page titles
+   * in Times. Caught in a screenshot, not by a test: nothing here fails when a
+   * root is missing, it just renders wrong.
    */
   .wave-docs-prose,
   .wave-docs-sidebar,
   .wave-docs-toc,
   .wave-docs-skip-link,
   .wave-docs-hero,
+  .wave-docs-explore,
+  .wave-docs-pager,
   .wave-docs-layout__sidebar,
   .wave-docs-search-trigger,
   .wave-docs-search-dialog {
@@ -652,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;
@@ -686,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>`. */
@@ -702,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
  * ------------------------------------------------------------------------ */
@@ -737,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;
     /*
@@ -770,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;
   }
 
@@ -992,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.
    *
@@ -1001,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);
@@ -1069,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
@@ -1085,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.
@@ -1158,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;
   }
 
   /*
@@ -1235,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;
   }
 
   /*
@@ -1280,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);
@@ -1290,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;
@@ -1313,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 {
@@ -1350,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);
   }
 
@@ -1405,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);
   }
 
@@ -1764,10 +2072,37 @@
     rotate: 90deg;
   }
 
+  /*
+   * A separator ends the block above it as much as it names the block below,
+   * and a rule says that in a way whitespace alone cannot: at 1rem of margin
+   * the gap read as "these two lists are a bit far apart" rather than as a
+   * division.
+   *
+   * ⚠️ THE RULE AND THE LABEL SHARE THE LIST'S OWN EDGE, WHICH IS ALSO THE
+   * ROWS'. A row is full-bleed — its hover surface spans the whole column, and
+   * so does the search field above it — so a rule on that edge divides the
+   * column, while an inset one floats inside it. The label sits on the same
+   * line, because a heading and the rule above it reading as one object is the
+   * whole reason the rule is there.
+   *
+   * Measured before this: the label sat at 24px, the rows' *icon* column. It
+   * headed a column of decoration, a step in from the words it names and a step
+   * out from the edge — aligned with neither.
+   *
+   * ⚠️ AND NO RULE ON THE FIRST CHILD, which would draw a line above nothing. A
+   * `meta.json` may open with `"---Reference---"`, and on that tree the very
+   * first thing in the navigation would be a hairline.
+   */
   .wave-docs-sidebar__separator-item {
     margin-block: 1rem 0.25rem;
   }
 
+  .wave-docs-sidebar__separator-item:not(:first-child) {
+    margin-block-start: 1rem;
+    padding-block-start: 1rem;
+    border-block-start: 1px solid var(--wave-docs-border);
+  }
+
   /*
    * ⚠️ NO `text-transform: uppercase`, AND IT USED TO HAVE ONE.
    *
@@ -1784,12 +2119,38 @@
    * single character. `letter-spacing` went with them: it exists to make caps
    * legible, and on sentence case it only reads as loose.
    */
+  /*
+   * The label starts where a row's content starts — the marker column when
+   * there is one, the words when there is not.
+   *
+   * ⚠️ THAT IS ONE NUMBER, NOT TWO, AND CHASING IT WITH `:has()` WAS THE WRONG
+   * SHAPE. A row's own `padding-inline` is what both modes have in common: with
+   * markers the icon sits on it, with `icons={false}` the text does. Matching
+   * the row's padding lands on whichever is there, in both modes, with no
+   * query and nothing threaded.
+   *
+   * The *rule* keeps the column's edge instead — it divides the column rather
+   * than naming anything. See `__separator-item`.
+   */
   .wave-docs-sidebar__separator {
     display: block;
-    padding-inline: 0.5rem;
+    padding-inline-start: 0.5rem;
     color: var(--wave-docs-fg-subtle);
     font-size: 0.75rem;
-    font-weight: 650;
+    /*
+     * ⚠️ THE WEIGHT IS THE LEVER HERE, NOT THE COLOUR. At 650 this label was
+     * heavier than the group titles it sits under and read as the loudest thing
+     * in the column — a divider out-shouting the navigation it divides.
+     *
+     * The obvious fix is a lighter colour, and there is none to reach for:
+     * `--wave-docs-fg-subtle` is already the lightest text token at 5.05:1 on
+     * the page, against WCAG 1.4.3's 4.5:1 floor for text this size — 0.55 of
+     * slack. `--wave-docs-border`, which is what the rule above it is painted
+     * with, measures 1.31:1 and is a line colour, not a text one.
+     *
+     * 500 drops it below the rows without touching the contrast at all.
+     */
+    font-weight: 500;
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -1828,6 +2189,374 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * 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
+ *
+ * Links to the pages either side of this one, emitted by `docs.Page` at the
+ * foot of the article.
+ * ------------------------------------------------------------------------ */
+
+@layer components {
+  /*
+   * ⚠️ TWO TRACKS, ALWAYS — WHICH IS WHY THE COMPONENT RENDERS AN EMPTY CELL
+   * RATHER THAN NOTHING AT EACH END OF THE SEQUENCE. With `auto-fit` or a
+   * plain flex row, the first page of a site puts its only link — `Next` — on
+   * the left, and every other page puts it on the right. The reader learns the
+   * position, and the one page where it moves is the one they see first.
+   *
+   * ⚠️ THE MEASURE *AND* THE CENTRING, WHICH IS TWO DECLARATIONS AND I SHIPPED
+   * ONE. `.wave-docs-prose` is capped and centred inside `__main`, so a
+   * `max-width` alone left this the right width in the wrong place: the
+   * paragraphs began at 440px and the pager at 304px, a 136px step directly
+   * under them. It belongs to the prose, so it takes both halves of what puts
+   * the prose where it is.
+   */
+  .wave-docs-pager {
+    display: grid;
+    margin-inline: auto;
+    /* `minmax(0, 1fr)`, never a bare `1fr`: that floors each track at its
+     * content's min-content width, so a long page title pushes the pair past
+     * the measure instead of wrapping inside it. */
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 0.75rem;
+    max-width: var(--wave-docs-measure);
+    margin-block-start: 3rem;
+  }
+
+  .wave-docs-pager__link {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 0.75rem 1rem;
+    border: 1px solid var(--wave-docs-border);
+    border-radius: var(--wave-docs-radius);
+    color: var(--wave-docs-fg);
+    text-decoration: none;
+  }
+
+  /*
+   * The next page is set to its own edge, so the pair reads outward from the
+   * middle — the direction each one takes you. `text-align` and not
+   * `align-items`, so a title that wraps to two lines stays aligned with
+   * itself rather than ragging against the box.
+   */
+  .wave-docs-pager__link[data-direction='next'] {
+    text-align: end;
+  }
+
+  /*
+   * ⚠️ THE ARROW POINTS OUTWARD, AND "OUTWARD" MIRRORS. Under `dir="rtl"` the
+   * grid's first track is on the right, so the *previous* link moves there and
+   * its arrow has to point right — the reverse of both rules above it. Same
+   * shape as the sidebar's chevron, and the same reason it is `[dir='rtl']`
+   * rather than `:dir(rtl)`: lightningcss rewrites the latter into a list of
+   * right-to-left *languages*, which is not the same question.
+   *
+   * Source order is load-bearing in the middle pair: `[dir='rtl'] .chevron` and
+   * `[data-direction='next'] .chevron` have the same specificity, so the
+   * mirror only wins by being written second.
+   */
+  .wave-docs-pager__chevron {
+    flex: none;
+    /* Sized down from the 16 it is drawn at: beside 12px type a full-size
+     * chevron is the loudest thing in the card. */
+    inline-size: 0.875rem;
+    block-size: 0.875rem;
+    rotate: 180deg;
+  }
+
+  .wave-docs-pager__link[data-direction='next'] .wave-docs-pager__chevron {
+    rotate: 0deg;
+  }
+
+  [dir='rtl'] .wave-docs-pager__chevron {
+    rotate: 0deg;
+  }
+
+  [dir='rtl']
+    .wave-docs-pager__link[data-direction='next']
+    .wave-docs-pager__chevron {
+    rotate: 180deg;
+  }
+
+  /* The arrow shares the caption's line, so the two read as one label and the
+   * title below starts at the card's own edge. */
+  .wave-docs-pager__caption {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    color: var(--wave-docs-fg-subtle);
+    font-size: 0.75rem;
+  }
+
+  .wave-docs-pager__link[data-direction='next'] .wave-docs-pager__caption {
+    justify-content: flex-end;
+  }
+
+  .wave-docs-pager__title {
+    font-weight: 600;
+  }
+
+  .wave-docs-pager__link:hover {
+    border-color: var(--wave-docs-border-strong);
+    background: var(--wave-docs-bg-subtle);
+  }
+
+  .wave-docs-pager__link:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .wave-docs-pager__link {
+      transition:
+        background-color 150ms ease-out,
+        border-color 150ms ease-out;
+    }
+  }
+}
+
 /* ---------------------------------------------------------------------------
  * Table of contents
  * ------------------------------------------------------------------------ */
@@ -2554,9 +3283,25 @@
     /* 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;
+    /*
+     * ⚠️ 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.
+     */
+    scrollbar-width: thin;
+    scrollbar-color: var(--wave-docs-border-strong) transparent;
   }
 
   /* First child of the navigation, above the tree. */
@@ -2574,6 +3319,47 @@
    * 20px transparent border for a while to answer to 44 while painting 24, and
    * a box the eye cannot see is a box the next person deletes.
    */
+  /*
+   * ⚠️ THE GRIP'S COLOUR IS A CUSTOM PROPERTY, NOT A SELECTOR FIGHT.
+   *
+   * Three things want to set it: the resting style, the reader's pointer, and
+   * the sidebar's own state — and the state lives on an *ancestor*, so
+   * `.sidebar[data-state] .trigger::before` outranks `.trigger:hover::before`
+   * by a whole class. Written as backgrounds that is a rule that silently kills
+   * hover on the one state that still needs it.
+   *
+   * Custom properties settle it by inheritance instead: the state sets them on
+   * the sidebar, the trigger sets them on itself under `:hover`, and a value on
+   * the element always beats one it inherited. No specificity, no `!important`,
+   * and the hover rule stays two lines long.
+   */
+  .wave-docs-layout__sidebar {
+    --wave-docs-trigger-fill: var(--wave-docs-border-strong);
+    --wave-docs-trigger-ink: var(--wave-docs-fg-muted);
+    --wave-docs-trigger-opacity: 0.4;
+  }
+
+  /*
+   * Blue means the grip is the thing to press; grey means it is at rest.
+   *
+   * The navigation is hidden and this is the way back to it — so a closed
+   * sidebar lights the grip, exactly as the pointer does. Open, the grip has
+   * nothing to offer that the visible column does not, and it goes quiet.
+   *
+   * ⚠️ `:not([data-state='open'])`, NOT `[data-state='closed']`. Below 64rem
+   * the sidebar starts closed and the attribute is absent until the reader
+   * chooses — a server-rendered page has no state at all. Matching only the
+   * explicit value leaves every first paint on a phone showing a grey grip in
+   * front of hidden navigation, which is the one moment the cue is for.
+   *
+   * The wide layout inverts the default, and overrides this below.
+   */
+  .wave-docs-layout__sidebar:not([data-state='open']) {
+    --wave-docs-trigger-fill: var(--wave-docs-accent);
+    --wave-docs-trigger-ink: var(--wave-docs-accent-fg);
+    --wave-docs-trigger-opacity: 1;
+  }
+
   .wave-docs-layout__sidebar-trigger {
     flex: none;
     /*
@@ -2603,7 +3389,7 @@
     padding: 4px;
     border: 0;
     background: none;
-    color: var(--wave-docs-fg-muted);
+    color: var(--wave-docs-trigger-ink);
     cursor: pointer;
   }
 
@@ -2627,8 +3413,10 @@
      * of the three dots, and nothing here scales with the pill: see `::after`.
      */
     height: 3.5rem;
-    border-radius: var(--wave-docs-radius-sm);
-    background-color: var(--wave-docs-border-strong);
+    /* A full pill: the radius is half the *short* side, so `9999px` clamps to
+     * exactly that whatever the two dimensions become. */
+    border-radius: 9999px;
+    background-color: var(--wave-docs-trigger-fill);
   }
 
   /*
@@ -2680,14 +3468,17 @@
    */
   .wave-docs-layout__sidebar-trigger::before,
   .wave-docs-layout__sidebar-trigger::after {
-    opacity: 0.4;
+    opacity: var(--wave-docs-trigger-opacity);
   }
 
-  .wave-docs-layout__sidebar-trigger:hover::before,
-  .wave-docs-layout__sidebar-trigger:hover::after,
-  .wave-docs-layout__sidebar-trigger:focus-visible::before,
-  .wave-docs-layout__sidebar-trigger:focus-visible::after {
-    opacity: 1;
+  /* On the element, not on the pseudo-elements: a custom property set here is
+   * inherited by both, and beats the sidebar's regardless of how specific the
+   * state selector that set it was. */
+  .wave-docs-layout__sidebar-trigger:hover,
+  .wave-docs-layout__sidebar-trigger:focus-visible {
+    --wave-docs-trigger-fill: var(--wave-docs-accent);
+    --wave-docs-trigger-ink: var(--wave-docs-accent-fg);
+    --wave-docs-trigger-opacity: 1;
   }
 
   /*
@@ -2702,11 +3493,6 @@
       var(--wave-docs-accent) 30%,
       transparent
     );
-    color: var(--wave-docs-accent-fg);
-  }
-
-  .wave-docs-layout__sidebar-trigger:hover::before {
-    background-color: var(--wave-docs-accent);
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -2830,6 +3616,18 @@
       margin-inline-end: 0;
     }
 
+    /*
+     * Unchosen means *open* up here, so the grip is at rest by default — the
+     * mirror of the rule above, and the reason that one is written as
+     * "not open" rather than "closed". A closed sidebar keeps the blue it
+     * inherits from there; nothing needs restating.
+     */
+    .wave-docs-layout__sidebar:not([data-state='closed']) {
+      --wave-docs-trigger-fill: var(--wave-docs-border-strong);
+      --wave-docs-trigger-ink: var(--wave-docs-fg-muted);
+      --wave-docs-trigger-opacity: 0.4;
+    }
+
     /* Nothing is covered, so nothing is scrimmed. */
     .wave-docs-layout__sidebar-scrim {
       display: none;