@waveso/docs 0.5.0 → 0.7.0

package/dist/styles.css

@@ -80,6 +80,25 @@
     --wave-docs-fg-subtle: oklch(0.54 0.015 262);
     --wave-docs-border: oklch(0.91 0.006 262);
     --wave-docs-border-strong: oklch(0.84 0.008 262);
+    /* The hero's grid, and the one place this package paints the brand ramp
+     * rather than a neutral.
+     *
+     * Wave 200 and Wave 300 from `@waveso/ui` verbatim — #AEDDFF and #7BC3FF.
+     *
+     * ⚠️ THE RIGHT STEP ON THE RAMP DEPENDS ON THE MASK, AND THE MASK CHANGED.
+     * It walked up to 300/400 while a radial gradient was holding the middle of
+     * the header at a few per cent — the numbers were chosen against a picture
+     * that was mostly suppressed. The radial is gone, so the same tokens paint
+     * at full strength across the whole header and read far heavier than they
+     * did. One step back is the same apparent weight.
+     *
+     * ⚠️ NOT `--wave-docs-border`. The grid is decoration behind a radial mask
+     * that leaves it near-invisible where the words are; a border is a boundary
+     * a reader has to be able to see. Sharing one token would tie a decorative
+     * tint to a functional contrast ratio, and the next change to either would
+     * be wrong for the other. */
+    --wave-docs-hero-grid: oklch(0.876 0.068 240);
+    --wave-docs-hero-grid-strong: oklch(0.793 0.112 245);
 
     /* Wave Blue #0074DE, darkened to #006EC8: the brand value clears 4.5:1 on
      * white but only 4.26:1 on `accent-subtle`, which is what the active sidebar
@@ -125,23 +144,47 @@
 
     --wave-docs-radius: 0.5rem;
     --wave-docs-radius-sm: 0.375rem;
-    /* The shell, per `docs/adr/001-shell-contract.md`. These four 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 them. */
-    --wave-docs-header-height: 3.5rem;
+    /* 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
+     * them. */
     --wave-docs-sidebar-width: 16rem;
+    /* The button the reader sees. The strip around it is `auto` — this plus 4px
+     * of padding on every side — so setting this is the whole of resizing the
+     * control, and the hit area grows with it rather than being a second number
+     * to keep in step. */
+    --wave-docs-trigger-width: 1.25rem;
     --wave-docs-toc-width: 15rem;
-    --wave-docs-shell-width: 100rem;
+
+    /*
+     * Where our sticky chrome starts, and the one thing only the host knows.
+     *
+     * A documentation section inside an application sits under that
+     * application's own bar. If theirs is sticky, ours has to start below it —
+     * and nothing in this package can measure that. This is the whole
+     * mechanical fix for it. A `standalone`/`embedded` mode flag was considered
+     * and rejected: it would have been an alias for this one line, which the
+     * host has to know the value of either way.
+     *
+     * ⚠️ `0rem`, NOT `0`, AND THE UNIT IS LOAD-BEARING. It is read inside
+     * `calc(100dvh - …)` on both sticky columns, and `calc(100dvh - 0)` is
+     * invalid at computed-value time — a unitless zero would not resolve to "no
+     * change", it would kill the `max-height` outright.
+     */
+    --wave-docs-chrome-offset: 0rem;
 
     /* How far below the top of the scrollport an anchored heading parks.
      *
-     * Derived, not set: it is the sticky header's height plus a rem of air, and
-     * the shell's sticky columns offset by the same token — so a host that
-     * changes the header height moves all three together. An earlier version of
-     * this comment said nothing else in the sheet read it, which stopped being
-     * true the moment the layout landed. */
-    --wave-docs-scroll-padding: calc(var(--wave-docs-header-height) + 1rem);
+     * Derived, not set, and one derivation rather than two. It carried a
+     * `--wave-docs-bar-height` term as well, because the sidebar used to take a
+     * strip shape *above* the content below 64rem and a heading had to clear
+     * that too. The sidebar is beside the content at every width now, so
+     * nothing of ours is ever over a heading.
+     *
+     * ⚠️ THE HOST TERM IS NOT OPTIONAL. An earlier draft made the desktop value
+     * a flat `1rem`, which parks a heading underneath the host bar of the very
+     * persona `--wave-docs-chrome-offset` exists for. */
+    --wave-docs-scroll-padding: calc(var(--wave-docs-chrome-offset) + 1rem);
     --wave-docs-font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo,
       Consolas, "Liberation Mono", monospace;
 
@@ -168,8 +211,8 @@
      * all, a 1440px viewport produced a ~140-character line.
      *
      * `--wave-docs-measure: none` opts out entirely, for a host whose own
-     * shell already constrains the column. See `docs/adr/001-shell-contract.md`
-     * — this is one of the five settable layout tokens. */
+     * shell already constrains the column. One of the six settable layout
+     * tokens. */
     --wave-docs-measure: 46rem;
   }
 
@@ -185,6 +228,11 @@
       --wave-docs-fg-subtle: oklch(0.665 0.015 265);
       --wave-docs-border: oklch(0.31 0.014 265);
       --wave-docs-border-strong: oklch(0.4 0.016 265);
+      /* Wave 900 and Wave 800. The light pair would be a white grid on a dark
+       * page — a ramp is not a colour, and the tint has to come from the end
+       * that belongs on this ground. */
+      --wave-docs-hero-grid: oklch(0.284 0.088 255);
+      --wave-docs-hero-grid-strong: oklch(0.351 0.118 255);
 
       --wave-docs-accent: oklch(0.72 0.14 248);
       --wave-docs-accent-hover: oklch(0.8 0.12 248);
@@ -228,6 +276,8 @@
     --wave-docs-fg-subtle: oklch(0.665 0.015 265);
     --wave-docs-border: oklch(0.31 0.014 265);
     --wave-docs-border-strong: oklch(0.4 0.016 265);
+    --wave-docs-hero-grid: oklch(0.284 0.088 255);
+    --wave-docs-hero-grid-strong: oklch(0.351 0.118 255);
 
     --wave-docs-accent: oklch(0.72 0.14 248);
     --wave-docs-accent-hover: oklch(0.8 0.12 248);
@@ -259,6 +309,28 @@
  * ------------------------------------------------------------------------ */
 
 @layer base {
+  /*
+   * ⚠️ THE SHELL DEPENDED ON THE HOST SHIPPING A RESET, AND MOST HOSTS DO.
+   *
+   * `.wave-docs-sidebar__link` is `width: 100%` with `0.5rem` of inline
+   * padding. Under `content-box` that is a 272px box in a 256px track, so the
+   * external-link icon `justify-content: space-between` pins to the far end
+   * lands 8px outside the sidebar and is clipped in half — measured, on the
+   * site in `site/`. Tailwind's preflight and every normalize-style reset set
+   * `border-box` globally, so the overflow was invisible in every project that
+   * has one, and visible on the only site here that ships no CSS at all.
+   *
+   * Scoped to this package's own namespace rather than to `*`. The prose
+   * renders a consumer's components as well as ours, and a global reset
+   * arriving inside a stylesheet they imported for their documentation is not
+   * ours to write — but every element carrying a `wave-docs-` class is one this
+   * package emitted and sized.
+   */
+  [class^='wave-docs-'],
+  [class*=' wave-docs-'] {
+    box-sizing: border-box;
+  }
+
   /*
    * The ground the ramp is composed against.
    *
@@ -315,6 +387,8 @@
   .wave-docs-sidebar,
   .wave-docs-toc,
   .wave-docs-skip-link,
+  .wave-docs-hero,
+  .wave-docs-layout__sidebar,
   .wave-docs-search-trigger,
   .wave-docs-search-dialog {
     font-family: var(--wave-docs-font-sans);
@@ -415,6 +489,13 @@
      * shipped, so in practice every consumer's first override was the same
      * container CSS — a default the package should have carried itself. */
     max-width: var(--wave-docs-measure);
+    /* ⚠️ AND CENTRED IN ITS TRACK, WHICH IS WHERE THE SHELL'S OLD CAP WENT.
+     * The shell used to be capped and centred, which pushed the sidebar off the
+     * page's inline start edge and left the closed navigation visible in the
+     * centring margin. The reading column is the thing that should not stretch,
+     * so it is the thing that is capped — and centring it here is what keeps a
+     * 2560px display from pinning the text against the navigation. */
+    margin-inline: auto;
   }
 
   .wave-docs-prose > * + * {
@@ -627,6 +708,33 @@
 
 @layer components {
   .wave-docs-table-scroll {
+    /*
+     * One cell, three things in it: the table and the two edge overlays below.
+     * `grid` rather than `relative` + `absolute` because an absolutely
+     * positioned child of a scroll container scrolls with the content, and
+     * these have to hold the scrollport's edges.
+     */
+    display: grid;
+    /*
+     * ⚠️ `max-content`, NOT `1fr`, AND THE DIFFERENCE IS WHETHER THE END EDGE
+     * EXISTS. A `1fr` track resolves against the scroll *port*, so the cell is
+     * narrower than the table it holds — and a sticky element can only travel
+     * inside its containing block, so the end overlay scrolled out of view and
+     * the shadow measured 0/255 at every scroll position. `max-content` makes
+     * the cell as wide as the table, which is the span both edges have to reach
+     * across.
+     *
+     * ⚠️ AND `max-content` IS THE *MIN*, WHICH IS THE ONLY SPELLING THAT DOES
+     * BOTH JOBS. A bare `max-content` track is exactly the table's width, so
+     * `width: 100%` resolved against that and a table narrower than the reading
+     * column stopped filling it — a bordered box with empty space down its
+     * inline end. `minmax(100%, max-content)` does not fix it either: a track
+     * only grows toward its max when there is free space, and inside a scroll
+     * container there is none, so it stayed at the port's width and the end
+     * overlay lost its containing block again. As the *floor*, `max-content`
+     * wins when the table is wider and `1fr` takes over when it is not.
+     */
+    grid-template-columns: minmax(max-content, 1fr);
     overflow-x: auto;
     border: 1px solid var(--wave-docs-border);
     border-radius: var(--wave-docs-radius);
@@ -667,7 +775,159 @@
     outline-offset: 2px;
   }
 
+  /*
+   * ⚠️ THE SAME AFFORDANCE, PAINTED ABOVE THE CONTENT INSTEAD OF BEHIND IT.
+   *
+   * The gradients above are a *background*, and an element's background is by
+   * definition below everything inside it — so the sticky `thead th`, which
+   * carries its own opaque fill, and every inline `<code>` chip, which carries
+   * another, punched holes in the shadow exactly where a wide table is most
+   * likely to be cut off. Found in a screenshot; no test could see it, because
+   * every assertion about the shadow was about declarations rather than pixels.
+   *
+   * These two overlay it. They share the table's grid cell, stick to the
+   * scrollport edges, and sit at `z-index: 2` — above `thead th`, which is 1,
+   * and above the chips, which are in flow.
+   *
+   * `opacity: 0` is the base state and it is load-bearing: see the `@supports`
+   * block below.
+   */
+  .wave-docs-table-scroll::before,
+  .wave-docs-table-scroll::after {
+    content: '';
+    grid-area: 1 / 1;
+    position: sticky;
+    z-index: 2;
+    width: 0.75rem;
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  /*
+   * ⚠️ THE TAPER IS A MASK, AND THE SHAPE WAS HALF THE ORIGINAL BUG.
+   *
+   * The background version used `radial-gradient(farthest-side at 0 50%)`,
+   * which reads well — soft at the top and bottom, strongest through the middle
+   * — and whose falloff is *proportional to the box*. On a tall table that puts
+   * the strength at the vertical centre and nothing at the ends: sampled on a
+   * real one, 5–9/255 of darkening beside the first body rows and 1/255 beside
+   * the header, which is where a reader looks first.
+   *
+   * So the horizontal falloff is a linear gradient, even down the whole height,
+   * and the taper is a mask with a *bounded* ramp. Proportional while the table
+   * is short — a quarter of the height at each end, which is the oval the
+   * original had — and capped at 5rem once it is tall, so a long table softens
+   * over its first and last 80px instead of over its first and last third.
+   * Measured at the cap: 0/255 at the very top edge, ~14 across the header row,
+   * 24 through the body. Soft where a shadow should be soft, present where a
+   * reader is looking.
+   */
+  .wave-docs-table-scroll::before,
+  .wave-docs-table-scroll::after {
+    mask-image: linear-gradient(
+      to bottom,
+      transparent 0,
+      rgb(0 0 0 / 0.55) min(8%, 1.25rem),
+      #000 min(24%, 5rem),
+      #000 calc(100% - min(24%, 5rem)),
+      rgb(0 0 0 / 0.55) calc(100% - min(8%, 1.25rem)),
+      transparent 100%
+    );
+  }
+
+  .wave-docs-table-scroll::before {
+    justify-self: start;
+    inset-inline-start: 0;
+    background: linear-gradient(
+      to right,
+      var(--wave-docs-scroll-shadow),
+      transparent
+    );
+  }
+
+  .wave-docs-table-scroll::after {
+    justify-self: end;
+    inset-inline-end: 0;
+    background: linear-gradient(
+      to left,
+      var(--wave-docs-scroll-shadow),
+      transparent
+    );
+  }
+
+  /*
+   * ⚠️ AN INACTIVE TIMELINE IS WHAT MAKES THIS CORRECT, NOT JUST CLEVER.
+   *
+   * A scroll timeline is *inactive* when its scroll container has no scrollable
+   * overflow in the axis, and an animation with an inactive timeline does not
+   * apply — so the base `opacity: 0` wins and a table that fits shows no shadow
+   * at all. No query asks whether it scrolls; the answer falls out of whether
+   * there is anything to scroll.
+   *
+   * ⚠️ `nearest`, NOT `self`. `self` names the element the animation is on, and
+   * the element here is a pseudo-element *inside* the scroll container rather
+   * than the container itself — so `scroll(self inline)` was inactive at every
+   * width, on every table, and the shadow simply never appeared. It looked
+   * exactly like the feature being unsupported: the `@supports` matched, both
+   * animations were listed on the pseudo, and the computed opacity was 0.
+   *
+   * Where it does overflow, scroll position alone drives the fade: no listener,
+   * no state, no hydration, on a table a reader may well meet before JS lands.
+   *
+   * Firefox skips this block — the feature is still behind
+   * `layout.css.scroll-driven-animations.enabled` as of 152, and is an Interop
+   * 2026 priority — and keeps the background gradients above, which is exactly
+   * what it renders today. The two are mutually exclusive on purpose: the
+   * `background: none` here is what stops a supporting browser darkening each
+   * edge twice.
+   */
+  @supports (animation-timeline: scroll()) {
+    .wave-docs-table-scroll {
+      background: none;
+    }
+
+    .wave-docs-table-scroll::before,
+    .wave-docs-table-scroll::after {
+      animation-timeline: scroll(nearest inline);
+      animation-timing-function: linear;
+      animation-fill-mode: both;
+    }
+
+    .wave-docs-table-scroll::before {
+      animation-name: wave-docs-scroll-shadow-start;
+    }
+
+    .wave-docs-table-scroll::after {
+      animation-name: wave-docs-scroll-shadow-end;
+    }
+  }
+
+  /* Absent while the start edge is at rest, present once it is not. */
+  @keyframes wave-docs-scroll-shadow-start {
+    0%,
+    2% {
+      opacity: 0;
+    }
+    8%,
+    100% {
+      opacity: 1;
+    }
+  }
+
+  /* Present until the end edge is reached. */
+  @keyframes wave-docs-scroll-shadow-end {
+    0%,
+    92% {
+      opacity: 1;
+    }
+    98%,
+    100% {
+      opacity: 0;
+    }
+  }
+
   .wave-docs-table {
+    grid-area: 1 / 1;
     width: 100%;
     /*
      * A FLOOR, NOT A SIZING MODE — and `width: 100%` is not one.
@@ -732,7 +992,20 @@
     white-space: nowrap;
   }
 
-  .wave-docs-table :is(thead, tbody tr + tr) {
+  /*
+   * ⚠️ `tbody tr + tr` ONLY. `thead` WAS IN THIS SELECTOR AND DOUBLED THE FRAME.
+   *
+   * The header is the first thing in the table, so its `border-block-start`
+   * landed directly against `.wave-docs-table-scroll`'s own border with nothing
+   * between them: measured at the top-left corner, two adjacent rows of
+   * `--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`.
+   */
+  .wave-docs-table tbody tr + tr {
     border-block-start: 1px solid var(--wave-docs-border);
   }
 }
@@ -797,10 +1070,19 @@
 
   .wave-docs-code {
     position: relative;
-    /* The `<pre>` inside carries the border and background; the figure is only
-     * a positioning context, and a default `<figure>` margin would indent the
-     * whole block by 40px. */
-    margin: 0;
+    /*
+     * ⚠️ `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.
+     *
+     * Zeroing all four also took the *block* margin, and `.wave-docs-prose > *
+     * + *` is the same specificity and declared earlier, so this won. Every
+     * code block sat flush against whatever followed it: two fences touching,
+     * a fence touching the paragraph under it. The flow spacing owns the block
+     * axis; this rule owns the inline one.
+     */
+    margin-inline: 0;
   }
 
   .wave-docs-code__title {
@@ -895,6 +1177,21 @@
   /* 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;
   }
 
   /*
@@ -1436,6 +1733,18 @@
     color: var(--wave-docs-fg-subtle);
   }
 
+  .wave-docs-toc__title {
+    margin: 0 0 0.5rem;
+    /* Aligns with the link text below it. The links carry a 2px rail on their
+     * inline start and 0.75rem of padding inside it; this has no rail, so it
+     * takes the rail's width as padding instead. */
+    padding-inline-start: calc(0.75rem + 2px);
+    color: var(--wave-docs-fg);
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.01em;
+  }
+
   .wave-docs-toc__link:hover {
     color: var(--wave-docs-fg);
     border-inline-start-color: var(--wave-docs-border-strong);
@@ -1457,8 +1766,8 @@
 /* ---------------------------------------------------------------------------
  * Layout
  *
- * The shell `docs.Layout` renders. Every class here is fixed by
- * `docs/adr/001-shell-contract.md` and is public API from 0.3.0.
+ * The shell `docs.Layout` renders. Every class here is public API from 0.3.0
+ * and changes only in a release that carries the migration.
  *
  * These are the first width-based media queries in this file. Before them there
  * were none at all — every `@media` was `prefers-color-scheme`,
@@ -1468,45 +1777,93 @@
 
 @layer components {
   /*
-   * Mobile first, and single-column by construction: the sidebar and the TOC
-   * are not laid out at all below 64rem, so nothing reserves a track for them.
+   * ONE SIDEBAR, AT EVERY WIDTH, AND IT IS A SHELL OF TWO.
+   *
+   *   .wave-docs-shell                       the query container
+   *   └─ .wave-docs-layout                   the grid
+   *      ├─ .wave-docs-layout__sidebar       paints nothing, and moves
+   *      │  ├─ …__sidebar-nav                the surface, and the one border
+   *      │  └─ …__sidebar-trigger            the strip — paints nothing at rest
+   *      ├─ .wave-docs-layout__sidebar-scrim
+   *      ├─ .wave-docs-layout__main
+   *      └─ .wave-docs-layout__toc
+   *
+   * There is no drawer, no dialog, no second control and no second copy of the
+   * tree. Pressing the trigger translates the sidebar; the trigger rides on the
+   * navigation's outer edge because it is the next flex item, not because a
+   * number says so.
+   *
+   * ⚠️ `@container`, AND EVERY WIDTH-BASED `@media` IS GONE WITH IT.
+   *
+   * This package is mounted at `/docs` inside applications that own the rest of
+   * the page. `@media` asks how wide the *screen* is, which is the wrong
+   * question: a host who puts this in a 700px panel on a 1920px monitor gets
+   * the wide layout and a reading column of about 60px. That is the same
+   * failure as the fixed header — a collision arriving from a direction no
+   * breakpoint can see. `@container` asks how wide the box we were *given* is,
+   * which is the question with an answer.
+   *
+   * ⚠️ AND THAT IS WHY THERE IS AN OUTER ELEMENT. A container query never
+   * matches its own container, so with `container-type` on the grid, no rule
+   * inside a query could touch `grid-template-columns` — which is exactly the
+   * declaration the layout has to change. One wrapper, and every rule below is
+   * addressable.
    */
-  .wave-docs-layout {
-    display: grid;
-    grid-template-columns: minmax(0, 1fr);
-    gap: 0 1.5rem;
-    /* 1rem on a phone, not 1.5rem: 48px of side padding is 15% of a 320px
-     * screen, and it took the reading column to 272px — under the 280px this
-     * package treats as the floor for a usable measure. Measured. */
-    padding-inline: 1rem;
-    /* Without this, `max-width` at the 100rem cap applies to the *content* box
-     * and the shell renders 48px wider than the token says — measured 1648
-     * against a declared 1600. */
-    box-sizing: border-box;
-  }
-
-  @media (min-width: 30rem) {
-    .wave-docs-layout {
-      padding-inline: 1.5rem;
-    }
-  }
-
   /*
-   * ⚠️ `contents`, NOT `none`, AND THAT IS NOT A STYLE PREFERENCE.
+   * ⚠️ NO `max-width` AND NO `margin-inline: auto` HERE, AND THAT IS A FIX
+   * RATHER THAN AN OMISSION.
    *
-   * The drawer `<dialog>` lives inside this wrapper, so that one nav DOM can
-   * serve both breakpoints. An element inside a `display: none` subtree
-   * generates no boxes at all — including a dialog promoted to the top layer —
-   * so `showModal()` would open a drawer that paints nothing, on every
-   * viewport narrower than 64rem. Which is to say: on the phones this drawer
-   * exists for.
+   * This box was capped at `--wave-docs-shell-width` and centred. Below the cap
+   * the layout's inline start edge and the viewport's are the same place, so
+   * `translate: calc(var(--wave-docs-trigger-width) - 100%)` put the closed
+   * navigation off the screen. Above it they are not: on a 2000px viewport the
+   * shell starts at 200, and the closed navigation parked at −56…200 — two
+   * hundred pixels of it still on screen, beside a trigger sitting 200px in
+   * from the edge. Measured.
    *
-   * `contents` makes the wrapper generate no box of its own, so it reserves no
-   * grid track, while the closed dialog inside stays hidden by the UA's own
-   * `dialog:not([open]) { display: none }`.
+   * The sidebar owns the page's inline start edge at every width now, so
+   * "closed" means off the screen by construction rather than by coincidence.
+   * What was capped is capped where it belongs: `.wave-docs-prose` holds
+   * `--wave-docs-measure` and centres itself in the track, so a 2560px display
+   * gets a reading column between its navigation and its table of contents
+   * instead of text pinned against one of them.
    */
-  .wave-docs-layout__sidebar {
-    display: contents;
+  .wave-docs-shell {
+    container-type: inline-size;
+    container-name: wave-docs;
+  }
+
+  .wave-docs-layout {
+    /* Absolutely positioned children of ours resolve against this, so nothing
+     * of ours resolves against the viewport and nothing of ours can land on a
+     * host's chrome. */
+    position: relative;
+    display: grid;
+    /*
+     * ⚠️ `auto`, AND THE SIDEBAR DECIDES WHAT IT MEANS. The track takes the
+     * sidebar's *outer* size, and the sidebar sets that with a negative margin:
+     * 44px whenever the navigation is off the page or covering the article,
+     * its full width only when it is meant to sit beside it. So one track
+     * expresses both modes and both states, and the layout never has to know
+     * which it is in.
+     *
+     * A fixed `var(--wave-docs-trigger-width)` here was the first attempt, and
+     * it could not grow — push mode silently behaved exactly like cover mode.
+     * Measured at 1440px: the article started at 68px in both states.
+     *
+     * In cover mode the article's measure is untouched by the toggle, because
+     * the track never changes: 330px at 390px whether the navigation is open or
+     * shut. In push mode it necessarily changes — that is what push means, and
+     * it is why cover exists for the widths where 330px is all there is.
+     */
+    grid-template-columns: auto minmax(0, 1fr);
+    gap: 0 0.5rem;
+    /* Nothing on the inline start: the trigger's track owns that edge. */
+    padding-inline: 0 0.5rem;
+    /* Without this, `max-width` at the cap applies to the *content* box and the
+     * shell renders 48px wider than the token says — measured 1648 against a
+     * declared 1600. */
+    box-sizing: border-box;
   }
 
   .wave-docs-layout__toc {
@@ -1526,259 +1883,713 @@
    * and removing `min-width: 0` alone passes; only removing both reproduces the
    * overflow. They are kept as a pair because they fail in opposite directions
    * — the track constraint protects a child that does not carry `min-width`,
-   * and `min-width: 0` protects a track someone respells — and because the one
-   * that is left looks arbitrary without the other beside it.
-   *
-   * No unit test can see any of this: the bug needs a wide child and a real
-   * layout engine, and jsdom reports every width as 0.
-   * `src/styles.browser.test.ts` is what stops a "simplification" here from
-   * reintroducing it silently.
+   * and `min-width: 0` protects a track someone respells.
    */
   .wave-docs-layout__main {
     min-width: 0;
     padding-block: 2rem 4rem;
+    /*
+     * ⚠️ EVERY `z-index` IN THE ARTICLE IS TRAPPED HERE, AND ONE OF THEM WAS
+     * PUNCHING THROUGH THE SCRIM.
+     *
+     * A sticky table header is `z-index: 1`, and so is the scrim. Same stacking
+     * context, equal z-index, and the header comes later in the document — so
+     * with the navigation open over a table on a phone, the header row was the
+     * one thing on the page that stayed bright. Measured on the installation
+     * page.
+     *
+     * Raising the scrim would have fixed that one element and left the next
+     * one. `isolation: isolate` makes the article its own stacking context, so
+     * nothing inside it — ours or a consumer's own content — can be compared
+     * against the scrim at all. The article resolves as a whole, at one layer,
+     * underneath.
+     */
+    isolation: isolate;
   }
 
-  /* 16rem sidebar + 46rem measure + two 1.5rem gutters = 65rem, so the sidebar
-   * arrives when there is room for it and not one pixel sooner. A 60rem
-   * breakpoint introduces it exactly where it starts eating the measure. */
-  @media (min-width: 64rem) {
-    .wave-docs-layout {
-      grid-template-columns: var(--wave-docs-sidebar-width) minmax(0, 1fr);
-    }
+  /* -------------------------------------------------------------------------
+   * The hero
+   *
+   * A page header a landing page opts into by declaring `actions` in its
+   * frontmatter. Every other page renders none of this.
+   * ---------------------------------------------------------------------- */
 
+  .wave-docs-hero {
+    position: relative;
     /*
-     * ⚠️ THE MOST DELETABLE-LOOKING LINE IN THIS FILE. IT IS NOT DELETABLE.
+     * ⚠️ BOTH, AND FOR TWO DIFFERENT REASONS. `isolate` keeps the grid's
+     * `z-index: -1` inside the hero instead of dropping it behind the page;
+     * `clip` holds the 150% rotated layer inside the header rather than letting
+     * it run down the article. `clip` rather than `hidden` so no scroll
+     * container is created and nothing sticky below is affected.
+     */
+    isolation: isolate;
+    overflow: clip;
+    /*
+     * ⚠️ THE NEGATIVE MARGIN CANCELS `.wave-docs-layout__main`'s
+     * `padding-block-start`, AND THE PADDING PUTS IT BACK INSIDE.
      *
-     * `display: contents` makes the dialog box vanish from layout **and from
-     * the accessibility tree**, so the `<DocsSidebar>` inside it becomes the
-     * sticky column directly. That is what lets one nav serve both breakpoints:
-     * one landmark, one copy of the links in the payload, nothing to keep in
-     * step. Remove it and the desktop sidebar disappears entirely — or, if
-     * someone "fixes" that by rendering a second sidebar outside the dialog,
-     * every page ships its nav twice and a screen-reader user gets two
-     * identical navigation landmarks.
+     * The grid is meant to reach the top of the article column. Left in the
+     * flow the hero starts 2rem down — measured at y=32 against a main at y=0 —
+     * so the pattern began with a band of blank page above it. Full-bleed
+     * upwards, and the space the header wants is its own padding rather than
+     * its parent's.
      *
-     * `:not(:modal)` so the drawer still opens as a real modal at any width;
-     * it is the same element, and a 64rem viewport with a 200% zoom is a
-     * narrow one.
+     * Horizontally there is nothing to cancel: `__main` carries no inline
+     * padding, so the hero already spans it exactly.
      */
-    dialog.wave-docs-layout__drawer:not(:modal) {
-      display: contents;
-    }
+    margin-block-start: -2rem;
+    margin-block-end: 3rem;
+    padding-block: 5rem 3.5rem;
+  }
 
-    .wave-docs-layout__sidebar {
-      display: block;
-      position: sticky;
-      top: var(--wave-docs-header-height);
-      /* `dvh`, not `vh`: with a mobile URL bar showing, `vh` is taller than the
-       * visible viewport, so the last few nav items sit under the chrome and
-       * cannot be reached. */
-      max-height: calc(100dvh - var(--wave-docs-header-height));
-      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. Costs ~15px on
-       * platforms with classic scrollbars; a jumping column costs more. */
-      scrollbar-gutter: stable;
-      padding-block: 2rem;
-    }
+  /*
+   * ⚠️ FOUR GRADIENTS, NOT AN SVG. The reference for this is a 100px SVG tile
+   * of twenty stroked lines, inlined as a data URI. Drawn as gradients it is
+   * the same picture with three properties that matter more than the fidelity:
+   * not one byte of data URI in the stylesheet, the line colour is a token so
+   * it follows the theme instead of being hardcoded black, and the tile is two
+   * numbers rather than twenty coordinates.
+   *
+   * The grid is 20px with every fifth line emphasised, offset 15px so the
+   * strong lines land at 15, 115, 215 — the tile boundary the SVG drew at 15.5
+   * with a 1px stroke. Strong pairs are listed first because a background image
+   * list paints first-on-top.
+   */
+  .wave-docs-hero::before {
+    content: '';
+    position: absolute;
+    /*
+     * Bigger than the box and offset by a quarter, so a 3° rotation cannot
+     * expose a corner. The overflow is clipped by the header.
+     */
+    inset-block-start: -25%;
+    inset-inline-start: -25%;
+    width: 150%;
+    height: 150%;
+    /* Below the scrims, which are at -1. */
+    z-index: -2;
+    pointer-events: none;
+    rotate: -3deg;
+    background-image:
+      repeating-linear-gradient(
+        to right,
+        transparent 0 15px,
+        var(--wave-docs-hero-grid-strong) 15px 16px,
+        transparent 16px 100px
+      ),
+      repeating-linear-gradient(
+        to bottom,
+        transparent 0 15px,
+        var(--wave-docs-hero-grid-strong) 15px 16px,
+        transparent 16px 100px
+      ),
+      repeating-linear-gradient(
+        to right,
+        transparent 0 15px,
+        var(--wave-docs-hero-grid) 15px 16px,
+        transparent 16px 20px
+      ),
+      repeating-linear-gradient(
+        to bottom,
+        transparent 0 15px,
+        var(--wave-docs-hero-grid) 15px 16px,
+        transparent 16px 20px
+      );
   }
 
-  @media (min-width: 80rem) {
+  /*
+   * ⚠️ THREE SCRIMS IN THE PAGE'S OWN COLOUR, PAINTED OVER THE GRID — NOT A
+   * MASK.
+   *
+   * Every earlier version of this masked the grid layer: two or three gradients
+   * multiplied with `mask-composite: intersect`. It worked, and it was never
+   * smooth. Mask layers multiply *alphas*, so the falloffs compound — two
+   * gentle ramps crossing make a hard shoulder, and one arithmetic slip turns
+   * the whole thing into a ring. Painting the page colour on top instead is
+   * ordinary alpha compositing of a solid: the ramps blend rather than
+   * multiply, and each one can be reasoned about on its own.
+   *
+   * It also means the percentages are of the header, not of a layer 150% its
+   * size — which is what three passes went wrong on.
+   *
+   * A separate element from the grid because this one must not rotate. The
+   * grid is at −3°; a scrim tilted with it would put its own edge on a slant.
+   *
+   * Painted first-on-top, so the order below reads outermost-last:
+   *
+   *   1. the reading scrim — a soft ellipse over the words
+   *   2. the bottom fade — nothing at the top, solid before the prose
+   *
+   * The corner vignette is not among them: it is the `box-shadow` below,
+   * because a gradient cannot be given a corner radius and this shape needs
+   * one.
+   */
+  .wave-docs-hero::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    pointer-events: none;
+    background-image:
+      radial-gradient(
+        ellipse 52% 58% at 38% 48%,
+        var(--wave-docs-bg) 0 25%,
+        transparent 80%
+      ),
+      linear-gradient(to bottom, transparent 40%, var(--wave-docs-bg) 90%);
     /*
-     * Inside the query on purpose. As a top-level rule this `:has()` reserves
-     * `--wave-docs-toc-width` of nothing at every width — measured at 390px it
-     * squeezed the article to 94px — because the TOC element is in the DOM at
-     * all sizes and only its `display` changes.
+     * ⚠️ THE VIGNETTE IS A SHADOW, NOT A RADIAL — BECAUSE A RADIAL HAS NO
+     * CORNER RADIUS.
+     *
+     * `radial-gradient` is only ever a circle or an ellipse: its shape is two
+     * radii and nothing else, so an elliptical vignette pinches the middle of
+     * every edge and opens the corners. An inset `box-shadow` with blur and
+     * spread fades inward from a *rounded rectangle*, which is the shape this
+     * wants — and `border-radius` is the knob the gradient never had.
+     *
+     * ⚠️ `inset: -4rem`, SO THE BOX'S OWN CORNERS FALL OUTSIDE THE HEADER. One
+     * `border-radius` sets both the shape the shadow fades from and the shape
+     * the box is clipped to; oversizing the box puts the clip out of sight and
+     * leaves only the inner shape doing any work.
+     *
+     * `corner-shape` turns that rounded rectangle into a true squircle. It is
+     * Chrome 139+ and degrades to an ordinary radius everywhere else, which is
+     * the same picture with slightly rounder corners — a progressive
+     * enhancement in the honest sense rather than a fallback nobody checked.
      */
-    .wave-docs-layout:has(.wave-docs-layout__toc) {
-      grid-template-columns:
-        var(--wave-docs-sidebar-width)
-        minmax(0, 1fr)
-        var(--wave-docs-toc-width);
-    }
+    inset: -5rem;
+    border-radius: 14rem;
+    corner-shape: superellipse(3);
+    /*
+     * ⚠️ THE SPREAD HAS TO CLEAR THE OVERHANG BEFORE IT DOES ANY WORK. The box
+     * sits 5rem outside the header on every side, so a spread of 5rem is solid
+     * only as far as the header's rim and the whole fade happens out of sight.
+     * 9rem puts the solid band 4rem inside, and the 10rem blur carries it in
+     * from there.
+     */
+    box-shadow: inset 0 0 10rem 9rem var(--wave-docs-bg);
 
-    .wave-docs-layout__toc {
-      display: block;
-      position: sticky;
-      /* `align-self: start`, or the sticky box stretches to the row height and
-       * has nothing left to travel within. */
-      align-self: start;
-      top: var(--wave-docs-header-height);
-      max-height: calc(100dvh - var(--wave-docs-header-height));
-      overflow-y: auto;
-      overscroll-behavior: contain;
-      padding-block: 2rem;
-    }
+    /*
+     * ⚠️ EVERY PERCENTAGE ABOVE IS OF THIS LAYER, NOT OF THE HEADER — AND THE
+     * LAYER IS HALF AS BIG AGAIN.
+     *
+     * The header occupies the middle third of it, from 33% to 67% on both axes.
+     * Written as `125% 100%` the radial's edge landed a long way outside the
+     * header, so what showed inside it was all near-centre: 15px of blank along
+     * every edge before the pattern faded up, measured. `83%` and `67%` are
+     * those numbers divided by the 1.5 — the same ellipse, expressed against
+     * the box it is actually seen through.
+     *
+     * The two linear layers are the edge fade, and they are why the pattern
+     * dissolves into the page on all four sides instead of being cut off by
+     * `overflow: clip`. Each one is transparent exactly at the header's edge —
+     * 33% and 67% of the layer — and opaque a few per cent inside it, so the
+     * ramp happens within the header rather than outside where nothing is seen.
+     * The vertical one is asymmetric on purpose: it holds full only to the
+     * midpoint before falling away, so the grid has faded out well before the
+     * prose begins.
+     *
+     * ⚠️ THE RADIAL AND THESE PULL IN OPPOSITE DIRECTIONS, WHICH IS THE POINT.
+     * The radial is transparent at the centre and opaque outward; these are
+     * opaque inside and transparent at the rim. Multiplied, what survives is a
+     * band between the two — a halo around the words that fades at the page
+     * and fades again where the reading starts.
+     */
   }
 
-  /* One declaration, for the only screenshot anyone takes on a 2560px display:
-   * uncapped, the sidebar pins to the far-left bezel and the TOC to the
-   * far-right, about 1500px apart, with the text floating between them. */
-  @media (min-width: 100rem) {
-    .wave-docs-layout {
-      max-width: var(--wave-docs-shell-width);
-      margin-inline: auto;
-    }
+  /*
+   * The heading, and it is the page's `<h1>` — `render` stands its own down
+   * when a page declares `actions`. Sized here rather than inherited from
+   * `.wave-docs-prose h1`, because it is outside the prose.
+   */
+  /*
+   * The words, aligned with the prose beneath them. The header itself spans the
+   * whole article track so the grid behind it is full-bleed; this is what keeps
+   * the title from sitting 70px left of the first paragraph.
+   */
+  .wave-docs-hero__body {
+    max-width: var(--wave-docs-measure);
+    margin-inline: auto;
   }
 
-  /* -------------------------------------------------------------------------
-   * Header
-   * ---------------------------------------------------------------------- */
+  .wave-docs-hero__title {
+    margin: 0;
+    color: var(--wave-docs-fg);
+    font-size: clamp(2.25rem, 1.5rem + 3vw, 3.5rem);
+    font-weight: 700;
+    line-height: 1.1;
+    letter-spacing: -0.02em;
+    text-wrap: balance;
+  }
 
-  .wave-docs-layout__header {
-    position: sticky;
-    top: 0;
-    /* Above the sticky sidebar and TOC, which establish their own stacking
-     * contexts; below the search dialog, which portals to `<body>`. */
-    z-index: 20;
-    height: var(--wave-docs-header-height);
-    background-color: var(--wave-docs-bg);
-    border-block-end: 1px solid var(--wave-docs-border);
+  /* `frontmatter.description`, which is otherwise only a `<meta>` tag. */
+  .wave-docs-hero__tagline {
+    margin: 1rem 0 0;
+    max-width: 34rem;
+    color: var(--wave-docs-fg-muted);
+    font-size: 1.125rem;
+    line-height: 1.6;
+    text-wrap: pretty;
   }
 
-  .wave-docs-layout__header-inner {
+  .wave-docs-hero__actions {
     display: flex;
-    align-items: center;
+    flex-wrap: wrap;
     gap: 0.75rem;
-    height: 100%;
-    /* Matches the grid's own cap and gutters, so the brand lines up with the
-     * sidebar and the actions with the TOC rather than floating past both. */
-    max-width: var(--wave-docs-shell-width);
-    margin-inline: auto;
-    padding-inline: 1rem;
-    box-sizing: border-box;
+    margin-block-start: 2rem;
   }
 
-  @media (min-width: 30rem) {
-    .wave-docs-layout__header-inner {
-      padding-inline: 1.5rem;
-    }
+  .wave-docs-hero__action {
+    display: inline-flex;
+    align-items: center;
+    /* 44px tall: the same minimum the sidebar's trigger answers to. */
+    min-height: 2.75rem;
+    padding-inline: 1.25rem;
+    border: 1px solid transparent;
+    border-radius: var(--wave-docs-radius);
+    font-size: 0.9375rem;
+    font-weight: 600;
+    text-decoration: none;
   }
 
-  .wave-docs-layout__title {
-    font-weight: 600;
-    /* The brand is not a link target here and must not swallow the row: a long
-     * product name would otherwise push search off the right edge. */
-    min-width: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+  .wave-docs-hero__action[data-variant='primary'] {
+    background-color: var(--wave-docs-accent);
+    color: var(--wave-docs-accent-fg);
   }
 
-  /* Pushes search and actions to the end, and stays correct when `title` is
-   * absent — which is why it is on the search wrapper rather than a margin on
-   * the title that would not exist. */
-  .wave-docs-layout__search {
-    margin-inline-start: auto;
+  .wave-docs-hero__action[data-variant='primary']:hover {
+    background-color: var(--wave-docs-accent-hover);
   }
 
-  .wave-docs-layout__actions {
-    display: flex;
-    align-items: center;
-    gap: 0.5rem;
-    /* When `search={false}` there is no auto margin ahead of this, so it
-     * carries its own. Both set, only one ever has room to apply. */
-    margin-inline-start: auto;
+  /*
+   * The tinted one. `accent-subtle` is the same surface the active sidebar link
+   * sits on, and its 4.5:1 pair is `accent` — so this is a contrast ratio the
+   * token test already checks rather than a new pairing to argue about.
+   */
+  .wave-docs-hero__action[data-variant='secondary'] {
+    background-color: var(--wave-docs-accent-subtle);
+    color: var(--wave-docs-accent);
   }
 
-  .wave-docs-layout__nav-trigger {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    /* 44px: the smallest target iOS and WCAG 2.5.8 both accept, and this is
-     * the only control on a phone that reaches the rest of the site. */
-    width: 2.75rem;
-    height: 2.75rem;
-    /* Optical alignment: the icon's own padding already insets it from the
-     * screen edge, so the button hangs left of the text below it without this. */
-    margin-inline-start: -0.75rem;
-    border: 0;
-    border-radius: var(--wave-docs-radius-sm);
+  .wave-docs-hero__action[data-variant='secondary']:hover {
+    border-color: var(--wave-docs-accent);
+  }
+
+  .wave-docs-hero__action:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .wave-docs-hero__action {
+      transition:
+        background-color 120ms ease-out,
+        border-color 120ms ease-out;
+    }
+  }
+
+  /* -------------------------------------------------------------------------
+   * The sidebar
+   * ---------------------------------------------------------------------- */
+
+  /*
+   * It paints nothing. The navigation carries the surface and the border, the
+   * trigger carries neither — so there is no third surface to keep in step with
+   * the other two, which is what made the strip read as filled every previous
+   * time this was drawn.
+   */
+  .wave-docs-layout__sidebar {
+    display: flex;
+    /* No gap: the trigger sits directly against the navigation's border. */
+    gap: 0;
+    width: max-content;
+    justify-self: start;
+    /*
+     * ⚠️ THE COLUMN IN THE PAGE, NOT THE PANEL THAT FOLLOWS THE VIEWPORT, AND
+     * KEEPING THOSE TWO APART IS THE POINT.
+     *
+     * This box was `position: sticky` with `height: 100dvh` — sized against the
+     * viewport while positioned against the layout, which is two reference
+     * frames in one element. The moment a host put anything above it, the two
+     * disagreed by exactly that much: with the UA's 8px of `body` margin the
+     * divider stopped 8px short of the top and ran 8px past the bottom, and it
+     * snapped into place as soon as the page scrolled and sticky engaged.
+     * Measured.
+     *
+     * Stretched to the grid row, it is exactly as tall as the docs region —
+     * starting where the host put it and ending where it ends, symmetric at any
+     * offset, with no token to set and nothing to keep in sync. The scrolling
+     * half is `position: sticky` on the two children, which is where a viewport
+     * measurement belongs.
+     */
+    align-self: stretch;
+    /* So a page shorter than a screen does not leave the sticky panel hanging
+     * below the column that draws its edge. */
+    min-height: calc(100dvh - var(--wave-docs-chrome-offset));
+    position: relative;
+    /* Above the scrim, which is above the article. */
+    z-index: 2;
     background: none;
-    color: var(--wave-docs-fg-muted);
-    cursor: pointer;
+    border: 0;
+    /*
+     * ⚠️ THE BOX IS ALWAYS `max-content`; ONLY ITS CONTRIBUTION MOVES.
+     *
+     * This one declaration is the whole of "the article does not get out of the
+     * way" — closed at any width, and open in cover mode. The box still paints
+     * its full width, so in cover mode it overlays; it just does not ask the
+     * grid for the room. Push mode drops it, and the same box takes its own
+     * space with nothing else changing.
+     */
+    margin-inline-end: calc(-1 * var(--wave-docs-sidebar-width));
+    /*
+     * Exactly the navigation's width, so it goes entirely off the page and the
+     * trigger's outer edge lands on the inline start edge — whatever the strip
+     * happens to be.
+     *
+     * ⚠️ THE SAME TOKEN AS THE MARGIN ABOVE, AND DELIBERATELY. It was
+     * `calc(var(--wave-docs-trigger-width) - 100%)` — "minus all of me, plus the
+     * trigger back" — which avoided naming the navigation but only worked while
+     * the strip had a width to name. The strip is `auto` now, so this is both
+     * shorter and the only spelling that cannot drift: the two declarations
+     * that move the sidebar read the same token.
+     */
+    translate: calc(-1 * var(--wave-docs-sidebar-width));
   }
 
-  .wave-docs-layout__nav-trigger:hover {
-    background-color: var(--wave-docs-bg-subtle);
-    color: var(--wave-docs-fg);
+  /*
+   * ⚠️ THREE STATES, NOT TWO, AND THE THIRD ONE IS WHY THERE IS NO FLASH.
+   *
+   * `data-state` absent means "nobody has chosen yet" — the server renders
+   * that, and CSS decides per mode: closed where the navigation would cover the
+   * article, open where it would sit beside it. So the first paint is already
+   * right at both shapes, with no JavaScript and nothing to correct. Once the
+   * reader presses the trigger their choice is explicit and wins at every
+   * width.
+   */
+  .wave-docs-layout__sidebar[data-state='open'] {
+    translate: 0;
+  }
+
+  /*
+   * ⚠️ NOT UNTIL THE SECOND FRAME. A transition declared at first paint
+   * animates the resolved state *in* from wherever the initial one was — the
+   * navigation visibly slides across on every page load. `data-ready` is set
+   * after mount, so the first paint is a jump nobody sees and every later
+   * change is animated.
+   */
+  @media (prefers-reduced-motion: no-preference) {
+    .wave-docs-layout__sidebar[data-ready] {
+      transition:
+        translate 200ms ease,
+        margin-inline-end 200ms ease;
+    }
   }
 
   /* -------------------------------------------------------------------------
-   * Drawer
+   * The navigation
    * ---------------------------------------------------------------------- */
 
-  dialog.wave-docs-layout__drawer {
-    /* A full-height panel against the inline start edge, not a centred box.
-     * `margin` rather than `inset`, because a dialog is centred by `margin:
-     * auto` in the UA sheet and only a margin overrides that. */
-    margin: 0 auto 0 0;
+  /*
+   * The only painted surface in the sidebar, and it has to be opaque: in cover
+   * mode it sits on top of the article, and a translucent one would put two
+   * columns of text through each other.
+   */
+  .wave-docs-layout__sidebar-nav {
+    flex: none;
     box-sizing: border-box;
-    width: min(20rem, 85vw);
-    max-width: none;
-    height: 100dvh;
-    max-height: none;
-    padding: 1.5rem 1rem;
+    width: var(--wave-docs-sidebar-width);
+    padding: 2rem 1rem;
     border: 0;
+    /*
+     * Cover mode only, and it is a different thing from the divider in push
+     * mode: there the line divides the page, here it is the edge of a panel
+     * lying on top of one. A panel's edge is the panel's height, so this one
+     * belongs on the panel.
+     */
     border-inline-end: 1px solid var(--wave-docs-border);
     background-color: var(--wave-docs-bg);
-    color: var(--wave-docs-fg);
+    /* The panel that follows the viewport: sticky, one screen tall, and its own
+     * scroller. `dvh`, not `vh` — with a mobile URL bar showing, `vh` is taller
+     * than the visible viewport and the last few nav items cannot be reached. */
+    position: sticky;
+    top: var(--wave-docs-chrome-offset);
+    height: calc(100dvh - var(--wave-docs-chrome-offset));
     overflow-y: auto;
-    /* Reaching the end of the nav must not start scrolling the page behind. */
+    /* 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;
   }
 
-  dialog.wave-docs-layout__drawer::backdrop {
-    background-color: oklch(0.2 0.02 262 / 0.55);
+  /* First child of the navigation, above the tree. */
+  .wave-docs-layout__search {
+    margin-block-end: 1rem;
   }
 
-  .wave-docs-layout__drawer-close {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    width: 2.75rem;
-    height: 2.75rem;
-    margin-block-end: 0.5rem;
-    margin-inline-start: auto;
+  /* -------------------------------------------------------------------------
+   * The trigger
+   * ---------------------------------------------------------------------- */
+
+  /*
+   * ⚠️ NO BACKGROUND AND NO BORDER, IN ANY STATE. 44px wide because that is
+   * Apple's minimum tap target and the strip *is* the target — it carried a
+   * 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.
+   */
+  .wave-docs-layout__sidebar-trigger {
+    flex: none;
+    /*
+     * Sticky for the same reason the navigation is: the column around it is the
+     * page's height now, and a control centred in *that* would sit halfway down
+     * a long document instead of halfway down the screen.
+     *
+     * ⚠️ AND IT IS ALSO WHAT POSITIONS THE BUTTON. The button and the dots are
+     * `position: absolute`, and an absolutely positioned box resolves against
+     * the nearest *positioned* ancestor — `sticky` qualifies, `static` does not.
+     * Without a positioned ancestor here they escape to the layout and paint a
+     * slab across the page. Measured.
+     */
+    position: sticky;
+    top: var(--wave-docs-chrome-offset);
+    height: calc(100dvh - var(--wave-docs-chrome-offset));
+    /*
+     * ⚠️ `auto`, SO THE TARGET GROWS WITH THE BUTTON. The strip was a fixed
+     * 2.75rem and the button was positioned inside it, which made the gap
+     * between them a third number nobody set: 24px of button left 10px a side,
+     * 16px left 14px. Sized by its content it is always the button plus 4px,
+     * and `--wave-docs-trigger-width` is the only thing to change.
+     */
+    display: grid;
+    place-items: center;
+    width: auto;
+    padding: 4px;
     border: 0;
-    border-radius: var(--wave-docs-radius-sm);
     background: none;
     color: var(--wave-docs-fg-muted);
     cursor: pointer;
   }
 
-  .wave-docs-layout__drawer-close:hover {
-    background-color: var(--wave-docs-bg-subtle);
-    color: var(--wave-docs-fg);
+  /*
+   * The button: `--wave-docs-trigger-width` × 80, and grey until hovered.
+   *
+   * ⚠️ IN FLOW, WHICH IS WHAT MAKES THE STRIP SIZE ITSELF. Absolutely
+   * positioned it contributed nothing, so the strip needed its own width and
+   * the gap between the two was whatever the subtraction happened to be. This
+   * is the only in-flow child, so the strip is exactly this plus its 4px of
+   * padding — one number, and the target follows the paint.
+   *
+   * `place-items: center` on the strip does the centring the insets used to.
+   */
+  .wave-docs-layout__sidebar-trigger::before {
+    content: '';
+    width: var(--wave-docs-trigger-width);
+    height: 5rem;
+    border-radius: var(--wave-docs-radius-sm);
+    background-color: var(--wave-docs-border-strong);
   }
 
   /*
-   * ⚠️ SCOPED TO OUR DRAWER, DELIBERATELY. `html:has(dialog:modal)` would lock
-   * the page for a consumer's own modal too — and unlock it again the moment
-   * ours closed underneath theirs.
+   * Three dots. Measured off docsify.js.org rather than reasoned about: three
+   * 4px circles 3px apart. One element and two `box-shadow` copies rather than
+   * three spans — no markup, and it follows `currentcolor` through the hover
+   * state for free. 4 + 3 + 4 + 3 + 4 is 18px tall, so the offset is 7.
+   *
+   * ⚠️ `::after`, AND THE ORDER IS LOAD-BEARING. Neither pseudo-element carries
+   * a `z-index`, so tree order decides which paints on top.
    */
-  html:has(dialog.wave-docs-layout__drawer:modal) {
-    overflow: hidden;
+  .wave-docs-layout__sidebar-trigger::after {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    width: 4px;
+    height: 4px;
+    translate: -50% -50%;
+    border-radius: 50%;
+    background: currentcolor;
+    box-shadow:
+      0 -7px 0 currentcolor,
+      0 7px 0 currentcolor;
   }
 
   /*
-   * Drawer furniture, hidden once the drawer is a column.
+   * ⚠️ THE STRIP'S HOVER LIGHTS THE BUTTON TOO, AND THAT IS WHAT MAKES IT ONE
+   * CONTROL. Hovering 44px of strip while the button inside it stays grey reads
+   * as a dead zone around a small target; Docsify pairs them for the same
+   * reason.
+   */
+  .wave-docs-layout__sidebar-trigger:hover {
+    background-color: color-mix(
+      in oklab,
+      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) {
+    .wave-docs-layout__sidebar-trigger,
+    .wave-docs-layout__sidebar-trigger::before,
+    .wave-docs-layout__sidebar-trigger::after {
+      /*
+       * ⚠️ ON THE PSEUDO-ELEMENTS TOO, NOT ONLY THE BUTTON. The dots are
+       * `background: currentcolor`, and an inherited colour changing does not
+       * start a transition on a descendant that has not declared one — the
+       * button would fade and the dots would snap.
+       */
+      transition:
+        background-color 120ms ease-out,
+        color 120ms ease-out;
+    }
+  }
+
+  /*
+   * ⚠️ AN OUTLINE, NOT THE FILL. These shared the hover rule for one commit,
+   * and `focus-indicators` caught it: a background change is the one thing
+   * forced-colours mode discards, so a keyboard reader there would have had no
+   * indicator at all.
+   */
+  .wave-docs-layout__sidebar-trigger:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: -2px;
+  }
+
+  /* -------------------------------------------------------------------------
+   * The scrim
    *
-   * ⚠️ AFTER the rules it overrides, not up with the other 64rem block. Same
-   * specificity means source order decides, and declared earlier this lost to
-   * the `display: inline-flex` above at every width — leaving a menu button
-   * and a close button sitting in a desktop layout that has nothing to open or
-   * close. Measured at 1280px: `flex`, not `none`.
+   * Cover mode only. `inert` keeps the keyboard out of what is underneath; this
+   * is what tells everyone else.
+   * ---------------------------------------------------------------------- */
+
+  .wave-docs-layout__sidebar-scrim {
+    /* Absolute inside the layout rather than fixed to the viewport: a fixed
+     * scrim would darken a host's own chrome along with our article. */
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    border: 0;
+    padding: 0;
+    background-color: oklch(0.2 0.02 262 / 0.55);
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .wave-docs-layout__sidebar[data-state='open']
+    ~ .wave-docs-layout__sidebar-scrim {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .wave-docs-layout__sidebar-scrim {
+      transition: opacity 200ms ease;
+    }
+  }
+
+  /* -------------------------------------------------------------------------
+   * Cover and push
+   *
+   * The whole of what differs between a narrow container and a wide one. Same
+   * markup, same classes, same control, same translate — only whether the
+   * article gets out of the way.
+   * ---------------------------------------------------------------------- */
+
+  /*
+   * ⚠️ A CUSTOM PROPERTY, BECAUSE JAVASCRIPT CANNOT ASK A CONTAINER QUERY.
+   * `matchMedia` answers about the viewport, which is the question this file
+   * deliberately stopped asking — so the mode is declared here and read back
+   * with `getComputedStyle`. One source of truth, and the breakpoint appears
+   * nowhere in the component.
    */
-  @media (min-width: 64rem) {
-    .wave-docs-layout__nav-trigger,
-    .wave-docs-layout__drawer-close {
+  .wave-docs-layout__sidebar {
+    --wave-docs-sidebar-mode: cover;
+  }
+
+  @container wave-docs (min-width: 64rem) {
+    .wave-docs-layout__sidebar {
+      --wave-docs-sidebar-mode: push;
+    }
+
+    /*
+     * ⚠️ THE DIVISION IS THE PAGE'S, SO IT IS DRAWN BY THE PAGE'S COLUMN.
+     *
+     * In push mode the sidebar is part of the layout and this line is what
+     * separates navigation from article — so it runs the full height of the
+     * docs region, top to bottom, wherever the host placed it. Drawn on the
+     * navigation instead it would be one screen tall, which is only the same
+     * thing when the layout happens to start at the viewport's top edge.
+     *
+     * `inset-inline-start` at the navigation's width rather than a border on
+     * the shell: the shell's own inline end is past the trigger, and the
+     * division belongs between the navigation and the article.
+     */
+    .wave-docs-layout__sidebar::after {
+      content: '';
+      position: absolute;
+      inset-block: 0;
+      inset-inline-start: var(--wave-docs-sidebar-width);
+      width: 1px;
+      background-color: var(--wave-docs-border);
+    }
+
+    /*
+     * Unchosen means open up here, where there is room for the navigation
+     * beside the article rather than on top of it — and open in push mode is
+     * the one combination that asks the grid for its own space.
+     *
+     * ⚠️ KEYED ON THE STATE, NOT THE MODE. Dropping the margin for the whole of
+     * push mode leaves a 300px hole in the grid whenever the sidebar is closed:
+     * the box is translated off the page and the track is still holding room
+     * for it.
+     */
+    .wave-docs-layout__sidebar:not([data-state='closed']) {
+      translate: 0;
+      margin-inline-end: 0;
+    }
+
+    /* Nothing is covered, so nothing is scrimmed. */
+    .wave-docs-layout__sidebar-scrim {
       display: none;
     }
+
+    /* And the panel's edge gives way to the page's division above. */
+    .wave-docs-layout__sidebar-nav {
+      border-inline-end: 0;
+    }
+
+    .wave-docs-layout {
+      gap: 0 1.5rem;
+      padding-inline: 0 1.5rem;
+    }
+  }
+
+  @container wave-docs (min-width: 80rem) {
+    .wave-docs-layout:has(.wave-docs-layout__toc) {
+      grid-template-columns: auto minmax(0, 1fr) var(--wave-docs-toc-width);
+    }
+
+    .wave-docs-layout__toc {
+      display: block;
+      /* Same reason as the article: its contents cannot be weighed against the
+       * scrim, only the column as a whole. */
+      isolation: isolate;
+      position: sticky;
+      /* `align-self: start`, or the sticky box stretches to the row height and
+       * has nothing left to travel within. */
+      align-self: start;
+      top: var(--wave-docs-chrome-offset);
+      max-height: calc(100dvh - var(--wave-docs-chrome-offset));
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      padding-block: 2rem;
+    }
   }
 }
 
@@ -1809,6 +2620,25 @@
     cursor: pointer;
   }
 
+  /*
+   * In the shell, the trigger fills whatever it is placed in — the width of the
+   * strip below 64rem, the width of the column above it.
+   *
+   * ⚠️ THIS USED TO BE A THREE-STEP `max-width` LADDER (9rem, 11rem at 30rem,
+   * 20rem at 48rem) AND EVERY NUMBER IN IT WAS HEADER ARITHMETIC. The trigger
+   * is `width: 100%`, so in a flex row its base was the whole row; the ladder
+   * existed to stop it starving the brand beside it, and at 390px it had
+   * ellipsised "Wave Docs" to "Wa…". With no header there is no row to share
+   * and no brand to leave room for, so the container decides.
+   *
+   * The bare `.wave-docs-search-trigger` keeps its own `max-width: 20rem` for
+   * the standalone case — a host rendering `DocsSearch` in their own header,
+   * where something else *is* competing for the row.
+   */
+  .wave-docs-search-trigger.wave-docs-layout__search {
+    max-width: none;
+  }
+
   .wave-docs-search-trigger:hover {
     border-color: var(--wave-docs-border-strong);
     color: var(--wave-docs-fg);
@@ -1828,6 +2658,18 @@
     white-space: nowrap;
   }
 
+  /*
+   * ⚠️ HIDDEN WHERE THE SHORTCUT CANNOT BE PRESSED, WHICH IS NOT A WIDTH
+   * QUESTION. `⌘K` is an instruction, and on a phone or a tablet it is one the
+   * reader cannot follow — a 10-inch tablet at 1024px would keep it under any
+   * breakpoint rule.
+   */
+  @media (hover: none) and (pointer: coarse) {
+    .wave-docs-search-trigger-kbd {
+      display: none;
+    }
+  }
+
   .wave-docs-search-trigger-kbd {
     flex: none;
     padding: 0.05rem 0.35rem;