@waveso/docs 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,660 @@
 # @waveso/docs
 
+## 0.12.0
+
+### Minor Changes
+
+- 3551951: **The search results and the sidebar say "there is more this way" the same way
+  the table does, and hide their scrollbars where they can.**
+
+  Four gradients on the search list, exactly as `.wave-docs-table-scroll` does it:
+  the two `local` covers are painted in the surface colour and travel _with_ the
+  rows, so each sits over its shadow only while that edge is at rest, and the two
+  `scroll` shadows are pinned to the box. A grey edge appears on precisely the side
+  that has rows off-screen, with no listener, no state and no hydration.
+
+  ⚠️ IT REPLACED A MASK, WHICH WAS THE WRONG TOOL TWICE OVER. A mask fades content
+  to _transparent_, so what showed through was the dialog's own white — a hole
+  rather than a shadow. And it cannot be conditional: CSS has no way to ask whether
+  there is anything above to scroll to, so the first and last rows were softened
+  even at rest.
+
+  ## The sidebar needs its shadow above the content, not behind it
+
+  ⚠️ `.wave-docs-sidebar` PAINTS ITS OWN GROUND, AND MUST. It is in the theme's
+  opt-in rule — the one that installs a ground wherever it installs a foreground
+  ramp — so a consumer mounting the tree alone gets one, and `styles.browser.test`
+  requires the shell to be a single surface. An element's background is painted
+  _below_ its children, so the four-gradient trick was covered by a child 480px
+  tall: measured 255/255 at the top edge with the nav scrolled — declared,
+  computed, and invisible.
+
+  So the navigation's overflow moved to an inner box, `.wave-docs-layout__sidebar-scroll`,
+  and the panel keeps only its edges.
+
+  ⚠️ THAT SPLIT IS THE FIX, AND EVERY VERSION BEFORE IT FOUGHT THE SCROLLER. An
+  absolutely positioned child of a scroll container is laid out against that
+  container's padding box and _joins its scrollable overflow_ — so nothing placed
+  inside a scroller is ever pinned to it. `position: sticky` only clamps, and a
+  clamp is still a thing that travels until it catches. With the scrolling on an
+  inner element the panel is an ordinary positioned box: `top: 0` and `bottom: 0`
+  are its own edges, and the bands have no scroll to have a position within.
+
+  The timeline is declared on the scroller and `timeline-scope`d up to the panel,
+  because a `scroll-timeline` name is visible to the declaring element's
+  descendants and these pseudo-elements belong to its parent.
+
+  ⚠️ AND THE SHADOW BELONGS TO THE PANEL RATHER THAN THE TREE, because
+  `.wave-docs-sidebar` paints an opaque ground — it is in the theme's opt-in rule,
+  and the shell has to be one surface — so a background on the scroller would be
+  painted underneath it. Measured 255/255 when it was.
+
+  ⚠️ AND THE NAV'S FADE IS A LENGTH, NOT A PERCENTAGE OF THE SCROLL. The table's
+  keyframes shape their fade in percentages, which are percentages of the
+  container's _total_ scroll range — fine on a table, wrong on a navigation. A nav
+  with 1000px of scroll turns the same `2%…8%` into 20px…80px, so the shadow spends
+  eighty pixels of scrolling arriving at full strength, which reads exactly like it
+  is moving with the content rather than pinned to the edge. `animation-range: 0
+1rem` makes it the same short distance whatever the nav's height, identical on a
+  six-page site and a three-hundred-page one, with plain fades for keyframes
+  because the shaping now lives in the range.
+
+  ⚠️ THE SCROLLBAR IS HIDDEN ONLY WHERE THE SHADOW EXISTS. Both live in the same
+  `@supports (animation-timeline: scroll())`, so Firefox — where scroll-driven
+  animations have not shipped — keeps the thin bar rather than losing the bar and
+  the shadow together. A scrollbar is the one cue that a column has more below it,
+  and taking it away before something replaces it trades a slab for nothing.
+
+  ⚠️ AND A SECOND TEST LEARNED THAT `getAnimations()` IS NOT "TRANSITIONS". A
+  scroll-driven animation's `finished` promise resolves when the _scroll position_
+  reaches the end, which is to say never on a panel sitting at the top — so
+  awaiting the whole list hung `sidebar.browser.test.tsx` for its full 15s timeout
+  the moment this shadow existed. `nav.browser.test.tsx` had already been bitten by
+  the table's; this is the second place the assumption lived.
+
+- 70649b8: **Search results get a glyph, a breadcrumb, and no scrollbar.**
+
+  **A page or a section, as an icon.** Which one is read off the `href` rather
+  than a new index field — a record with an anchor is a section within a page and
+  one without is the page itself, which is what `buildSearchIndex` means by its
+  lead record — so the records did not grow by a byte.
+
+  ⚠️ AND THE ICON IS NOT DECORATION, IT IS THE ALIGNMENT. With no icon a result's
+  heading sat on the same column as the input's _magnifier_ while the input's own
+  text sat 24px right of it: three left edges where a reader expects two, which is
+  what made the dialog read as stacked levels rather than as a list under a field.
+  The icon takes the magnifier's column and the text takes the input's, so the two
+  rows are the same shape. Measured: 18px and 42px, both rows, plus the footer's
+  key caps on the 18.
+
+  **The second line is a breadcrumb.** The segments were always a trail from the
+  site's root to the page; slashes made them read as a URL to parse and `›` makes
+  them read as what they are. ⚠️ SAFE ONLY BECAUSE THAT LINE IS `aria-hidden` —
+  more than one screen reader pronounces the character, which is exactly why
+  `spokenName` joins with commas instead. The two lines carry the same fact in the
+  form each audience can use.
+
+  ⚠️ THE SEPARATOR IS THE PACKAGE'S OWN CHEVRON, NOT A CHARACTER, AND TWO
+  CHARACTERS WERE MEASURED AND REJECTED FIRST. `›` (U+203A) inks 4.93px tall in
+  the shipped mono face at 11px, against 6.32 for an `s` and 8.51 for a `b` — it
+  sat visibly below the words it separated. `❯` (U+276F) inks 8.03 and fixed the
+  height _on one machine_: `ui-monospace` resolves to SF Mono here, Consolas on
+  Windows, Liberation Mono on Linux, and a glyph missing from one of those falls
+  back to another face at another width. U+3009 already demonstrated exactly that,
+  measuring 11.24px against the 6.62 cell.
+
+  An SVG has no font to be missing from — and it is the same Lucide chevron the
+  sidebar and the pager draw, which is the real argument: everything else here is
+  that one set.
+
+  ⚠️ AND THE TRAIL IS SET IN THE SANS, NOT IN THE MONO IT STARTED IN — WHICH IS
+  WHAT MADE THE SEPARATOR RELIABLE. A monospace face advances every glyph one
+  cell, so the segments marched on a rigid grid an icon could not join, and its
+  metrics are whatever the machine resolves: SF Mono here, Consolas on Windows,
+  Liberation Mono on Linux. The cap height an inline glyph is sized against
+  therefore moved from reader to reader, which is the same portability problem
+  that ruled out `›` and `❯` as characters — arriving a second time through the
+  face rather than through the glyph. Proportional sans has ordinary spacing and
+  one set of metrics to match. `font-size` goes up a notch with it, because a
+  mono face reads larger at the same size and holding the number would have
+  shrunk the line.
+
+  ⚠️ AND THE `viewBox` IS CROPPED TO THE STROKE, WHICH IS WHAT RETIRED FOUR
+  CORRECTIONS. On Lucide's full 24 grid the chevron occupies x 9–15 and y 6–18,
+  so a square box around it was five sixths air across and half air down — and
+  every one of those gaps had to be subtracted back by hand: a `vertical-align`,
+  a negative `margin-inline`, a negative `margin-block`, and a size chosen to
+  make the surplus come out right. `8 5 8 14` is the painted extent, caps and
+  joins included. The box is the glyph, so it sits on the baseline the way a
+  letter does with nothing declared, and the air beside it is one positive
+  `margin-inline`.
+
+  ⚠️ AND IT CARRIES `overflow: visible`, WITHOUT WHICH THE POINT IS FLAT. An
+  `svg` clips to its viewport by default and this `viewBox` is exactly the
+  stroke's extent, so the round join at the tip lands on the box's own edge and
+  loses its outermost anti-aliased pixel. Nothing overlaps anything: what spills
+  is a fraction of a pixel.
+
+  ## The scrollbar is hidden, and it cannot be conditional
+
+  ⚠️ THERE IS NO CSS WAY TO SHOW A SCROLLBAR ONLY WHILE SCROLLING. That behaviour
+  is the platform's: macOS draws overlay scrollbars that fade in on scroll and out
+  after it, and this list gets it for free there. Windows and Linux draw a classic
+  one that is always present, and the only ways to make it come and go are a
+  JavaScript timer toggling a class or a scrollbar drawn from scratch in script —
+  which is what a `ScrollArea` component is, and neither belongs in a package whose
+  whole argument is what it does _not_ ship to a reader.
+
+  So it is hidden, as `@waveso/app` does with `.scrollbar-none`. What replaces it
+  is the keyboard rather than a fade: the footer says `↑ ↓ Select`, the list is
+  driven by `aria-activedescendant`, and arrowing past the last visible row scrolls
+  it and loads the next page.
+
+  ⚠️ AND `pageSize` STAYS A WINDOW, NOT A CAP. It was a hard ceiling of 8 once, and
+  that was removed with measurements: on a six-page site "docs" matches 18, so
+  results were unreachable and the live region announced "8 results" — not a
+  smaller truth but a false one. Rendering every row of a 300-page corpus costs
+  40ms, 128ms at 4x throttle, which is what paging exists to avoid; the ceiling
+  was never what made it fast.
+
+  The size budget moves with the glyphs, and the figures the README and the
+  installation page publish move with it — a document here may not understate what
+  this package costs.
+
+- 78053a6: **Nothing in the search dialog is selected until the reader selects it.**
+
+  Typing lit the first result the instant it arrived, so a row changed under a
+  reader for something they had not chosen — and on this package's accent that
+  reads as a decision already made. `activeIndex` starts at `-1` now: an arrow key
+  or the pointer moving over a row is what selects.
+
+  ⚠️ AND EVERY GUARD FOR IT ALREADY EXISTED, WHICH IS WHY THIS IS ONE NUMBER.
+  `hits[-1]` is `undefined`, so no `aria-activedescendant` is written and Enter
+  returns without opening anything. The one place that needed teaching is the
+  arrow keys: they wrap modulo the list, and `(-1 - 1 + n) % n` is the _second to
+  last_, so Up from a fresh query landed one short of the end.
+
+  **The active row is the table header's grey**, easing on the same 150ms the
+  sidebar's rows use. Moving the pointer over a result activates it, so hovering
+  _is_ this state; there is no second rule for it.
+
+  It has been four things: a 2px accent ring, which read as a component borrowed
+  from somewhere else and came and went as a reader arrowed; the trigger's border
+  pair, which meant bordering _every_ row to make one edge legible and turned a
+  list into a stack of cards; an accent tint, which was the same colour family as
+  the field above it. A row is a list item and its state is a colour — the field is
+  a control, and that is what wears the trigger's border.
+
+  ⚠️ `bg-subtle` ON `bg` IS ABOUT 1.02:1, SO THE TINT IS A HINT AND NOT AN
+  INDICATOR. The marker going `fg-subtle` to `fg` is the part that carries the
+  state — text contrast rather than non-text, and the sidebar's own hover. What
+  must not happen is the tint being left to carry it alone.
+
+  ## The field stops drawing a ring it could never put down
+
+  ⚠️ A TEXT INPUT MATCHES `:focus-visible` WHENEVER IT IS FOCUSED, HOWEVER FOCUS
+  ARRIVED — that is the spec, not a heuristic — and this dialog focuses its input
+  the moment it opens. So the accent ring was not a state, it was the field's
+  permanent appearance, and it stopped the field looking like the bordered grey
+  control the reader clicked to get there.
+
+  The edge darkens to `--wave-docs-border-strong` instead, which is what the
+  trigger does under the pointer, so the field is the trigger in both of its
+  states.
+
+  ⚠️ AND THE INDICATOR IS NOT LOST WITH IT, BECAUSE A TEXT FIELD HAS ONE OF ITS
+  OWN. The caret is the platform's focus indication for a text box, it is in this
+  field the whole time the dialog is open, and it is what a reader looks for to see
+  where typing goes. That is a different argument from the one this rule used to
+  reject: "the dialog frame is the indicator" was a _static_ border that looked
+  identical focused and unfocused, and indicated nothing. This edge changes.
+
+  ## The list fades at both edges
+
+  A mask on the scrollport, so the row being cut off is the one that softens. It
+  does not travel with the content: a mask paints against the element's own box, so
+  the two stops stay at the top and bottom of the _port_ while the rows move under
+  them.
+
+  ⚠️ IT IS UNCONDITIONAL, WHICH IS THE ONE THING TO KNOW. CSS cannot ask "is there
+  anything above this to scroll to" — the table's shadow answers that with a
+  scroll-driven animation whose timeline goes inactive when nothing overflows, and
+  a mask has no equivalent. So the first and last rows carry a little of it at
+  rest. At `1.25rem` against a row nearer three times that, it costs the top pixel
+  or two of a heading and buys never guillotining one.
+
+  ## The field, and the gap under it
+
+  **The field is the trigger, expanded.** Same border, same fill, same radius. It
+  was a border with no fill — two frames a few pixels apart — and briefly a fill
+  with no border, which is a tinted band rather than a control. The trigger has
+  always been both, and both together are what reads as a field.
+
+  ⚠️ THE PADDING IS NOT COPIED WITH THEM. The trigger pays `calc(0.5rem - 1px)`
+  because it is a compact control in a sidebar; the field pays
+  `calc(0.75rem - 1px)` because its glyph has to land on the column the results
+  and the footer sit on. The `- 1px` is the border either way — content inside a
+  bordered box starts a border further in.
+
+  The field takes the base radius and the result rows take `-sm`, which is the tier
+  system doing what it says: both are controls, and a result row is a list item.
+
+  ⚠️ AND THE GAP UNDER THE FIELD WAS PAID TWICE. The field's margin and the result
+  list's top padding both contributed, so the space between the input and the first
+  result was double the space above the input — a doubled gap in the one place a
+  reader's eye travels on every keystroke. The list drops its top padding; the
+  field keeps its margin, because an empty result list is `display: none` and a gap
+  paid from there would vanish on the query that matches nothing.
+
+### Patch Changes
+
+- 688a84c: **The search dialog lines up on one column, and its input is a field rather
+  than a band.**
+
+  The input row was flush to the dialog's frame, so it could only round the two
+  corners it shared with it and needed a rule underneath to separate it from the
+  results. Inset by the same margin the results list uses, it is a box like they
+  are — all four corners rounded, and the gap does the separating.
+
+  ⚠️ AND ITS RADIUS IS THE DIALOG'S MINUS THE GAP, NOT THE DIALOG'S. A rounded box
+  inset inside a rounded box is concentric only at `outer - gap`; equal radii run
+  the two corners at different curvatures six pixels apart and the field reads as
+  pasted onto the dialog rather than set into it.
+
+  **One column, measured from the bottom up.** The footer's key caps are the
+  anchor — the one row whose left edge is a drawn object — and the results' text
+  and the input's magnifier are measured to it. All three now start 18px from the
+  dialog's inner edge.
+
+  ⚠️ BOXES, NOT INK. A cap's arrow sits its own border and `0.4em` of padding
+  inside the cap, so aligning the _glyphs_ would put every other row on a column
+  that moves whenever the footer's font size does.
+
+  ⚠️ AND THE INPUT ROW PAYS `calc(0.75rem - 1px)` BECAUSE IT IS THE ONE ROW WITH A
+  BORDER. Content inside a bordered box starts a border further in than content
+  inside an unbordered one, so equal padding misses by exactly that — the same
+  subtraction `--wave-docs-panel-inset` exists for.
+
+## 0.11.0
+
+### Minor Changes
+
+- 5730af3: **The code frame wears the panel.** A fence is now an outer card holding a
+  header row — the filename or the language on the left, the copy button on the
+  right — and an inset surface with the code on it, dressed by the same
+  `.wave-docs-panel` rules as "where to go next".
+
+  ⚠️ THE `<figcaption>` STAYS A DIRECT CHILD OF THE `<figure>`, WHICH IS WHY THIS
+  HAS NO HEADER WRAPPER. A `figcaption` has to be the first or last child of its
+  figure; inside the `.wave-docs-panel__header` `<div>` that "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 lays its header out on a grid and shares
+  the primitive's _insets_ rather than its header element. The button stays out of
+  the caption for the matching reason: a `<button>` inside a `<figcaption>`
+  contributes its accessible name to the figure's, so `swap.ts` would announce as
+  "swap.ts Copy code from swap.ts".
+
+  ⚠️ AND A TITLE IS WHAT DECIDES WHETHER THERE IS A FRAME AT ALL. With one, 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 — which is what Mintlify does, and what stops an unnamed fence from
+  carrying a reserved slot with nothing in it.
+
+  A language is not a title for this purpose. A fence declaring `ts` and no
+  filename is still an untitled fence, and a band holding a two-letter badge is
+  the same empty header with a word in it. `data-lang` stays on the figure for
+  anyone selecting on it.
+
+  One shape of markup, switched in the stylesheet rather than in the pipeline: two
+  markup paths mean two fixtures, and the one that is not on screen is the one
+  that rots.
+
+  **The copy button no longer hides until you hover.** It faded in on `:hover` or
+  `:focus-within` because it was 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 stays
+  empty until you point at it reads as a rendering fault — 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. It is still `visibility: hidden` until the runtime attaches, which is
+  the structural promise and is unchanged.
+
+  ## Three things the restructure moved, each of which was a defect
+
+  ⚠️ THE `<pre>` DRAWS NO FRAME OF ITS OWN ANY MORE. It carried the border, the
+  radius and the background; inside a `.wave-docs-panel__body` that carries all
+  three, that draws the frame twice one pixel apart. `pre:not(.shiki)` keeps its
+  own, because an excluded fence is never wrapped.
+
+  ⚠️ AND ITS INLINE PADDING IS `1rem` BECAUSE THAT IS `--wave-docs-panel-inset`,
+  not because it is a round number. The label sits at that inset plus the
+  surface's border; the code sits at the surface's border plus this. The
+  `1.125rem` it was put the first character 2px right of the filename above it —
+  visible, and attributable to nothing.
+
+  ⚠️ AND THE FOCUS RING ON THE `<pre>` IS INSET NOW. Shiki gives it
+  `tabindex="0"` so a keyboard reader can scroll a wide block, and the surface
+  around it is `overflow: hidden` so a square corner cannot poke through the
+  frame's rounded one — which clipped a `+2px` outline away to nothing.
+  `styles.test.ts` reads rules as text and would have gone on passing.
+
+  ## The panel grew two properties, both to settle a cascade rather than a taste
+
+  `--wave-docs-panel-surface` is the inset surface's ground, and its default lives
+  in a `var()` fallback rather than in a declaration. `.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. Moving the ground to a property did not fix it either — 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.
+  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.
+
+  `--wave-docs-panel-header-row` floors the header. With a label the row is the
+  label's height and with none it is the button's, and a page mixing titled and
+  untitled fences showed two header heights.
+
+  The frame's markup now has one home — `codeFrameMarkup` — that the browser tier
+  mounts and the plugin tier asserts the pipeline agrees with. Written out
+  separately in both, a hand-written fixture goes on describing a frame the
+  pipeline stopped emitting while every assertion measuring it stays green.
+
+- 793d0f7: **"Where to go next": a question per row, and the page that answers it.** A page
+  opts in from its frontmatter:
+
+  ```yaml
+  explore:
+    - question: How a person is recognised across servers
+      href: ./identity.md
+    - question: What happens when the network fails
+      href: ./delivery.md
+  ```
+
+  A sidebar is a structure; this is a router. It says _why_ a reader would go
+  somewhere, which no tree of titles can — so the same component is a landing
+  page's onboarding and an ordinary page's footnote.
+
+  ⚠️ THE LINK TEXT COMES FROM THE NAVIGATION. An `href` pointing at a page in the
+  tree takes that page's own name, so renaming it updates every block that points
+  at it — the same tree the sidebar and the pager read. Name a `title` only where
+  the tree cannot answer: an external link, or a page kept out of the navigation.
+
+  ⚠️ AND AN HREF THAT RESOLVES TO NEITHER STOPS THE BUILD. Falling back to the
+  href renders a URL where a sentence should be — "Where this runs and what that
+  buys → /docs/infrastructure" — on a page that builds cleanly, and nothing else
+  in the pipeline would notice. The frontmatter is authored and the author is
+  right there, so the error names the page and both fixes.
+
+  ⚠️ A LIST, NOT A TABLE, WHICH IS WHAT THE MARKDOWN IT REPLACES HAD TO BE. A
+  screen reader announces "table, 2 columns, 7 rows" for what is a list of links
+  with descriptions, and asks the reader to navigate it by cell. Two columns of
+  sentence-length questions are also cramped in a narrow box, where the rows stack
+  instead — a `@container` query, because a host can hand this a 500px panel on a
+  1920px monitor.
+
+  One frame with hairlines between the rows rather than a stack of cards: they are
+  the same question asked several ways, and separate boxes say several unrelated
+  things. The rule is a _top_ border on every row but the first — `:last-child`
+  leaves a doubled line the moment anything is appended to the list.
+
+  ## And the frame is a primitive, not this component's furniture
+
+  `.wave-docs-panel` is 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. "Where to go next" is the first thing to wear it; a code frame is the
+  obvious next, and two copies of the same three rules is how they drift apart.
+
+  ⚠️ 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; anything else runs the corners at different curvatures and the inner box
+  reads as _pasted onto_ the frame rather than set into it. The new
+  `--wave-docs-radius-lg` is chosen so the arithmetic lands on an existing token:
+  `1rem` outer minus `0.5rem` of padding is `--wave-docs-radius`.
+
+  The header sits in the frame's padding and draws no rule of its own — the inset
+  surface below already draws the line, and a border there is a second one a pixel
+  away from the first.
+
+  ⚠️ AND THE PANEL EXPORTS `--wave-docs-panel-inset`, WHICH IS NOT THE SAME NUMBER
+  AS ITS PADDING. The title sits at the frame's padding; anything inside the body
+  sits at that padding _plus the body's own border_, so the two columns miss each
+  other by a pixel per border. Measured before it existed: the rows started 9px
+  right of the heading above them — a number that appears in no rule and reads as
+  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.
+
+  It renders above the pager. The two answer different questions and both belong
+  there: this is the semantic answer, the pager the linear one.
+
+  A real `<h2>` names it, not an `aria-label` — a reader moving by heading would
+  pass straight over a region named only by an attribute.
+
+  ## The key is `explore`, and neither `next` nor `steps` would do
+
+  `next` is unusable in this package. `src/next.ts` is the Next.js adapter, so
+  two files one directory apart would carry the same name for entirely different
+  things, and `doc.frontmatter.next` would read like a routing hook rather than
+  a block of prose.
+
+  `steps` is wrong for a different reason: these rows are a _branch_, not a
+  sequence. A reader picks one and ignores the rest, and none of them is first.
+  A numbered "1 -> 2 -> 3" component is a real and separate thing worth building
+  later, and `steps` is the name it will need.
+
+  The rendered heading is still "Where to go next" — `next` in prose is fine,
+  it is only the identifier that had to move.
+
+  No client JavaScript. New: `DocsExplore` at `@waveso/docs/react/explore`,
+  `explore` in frontmatter, and `explore` in `labels`.
+
+- c871d2f: **One radius scale, taken from `@waveso/ui`, retunable from a single line.**
+
+  Three tiers, all `calc()` off one root, so which corner a box gets is decided by
+  what _kind_ of box it is rather than by how big it happens to be:
+
+  | Token                   | What takes it                                               |
+  | ----------------------- | ----------------------------------------------------------- |
+  | `--wave-docs-radius-sm` | inline chips, small controls, focus rings on those          |
+  | `--wave-docs-radius`    | controls, overlays, and the panel's inset surface           |
+  | `--wave-docs-radius-lg` | every block in the reading flow, and the panel's outer edge |
+
+  ⚠️ THE BLOCK TIER WAS SPLIT. 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 — and a table read as aggressively round next
+  to the callout above it. 19 was measured off a reference site, which is a fine
+  way to pick a number and a bad way to pick a _system_.
+
+  ⚠️ AND THE NUMBERS ARE `@waveso/ui`'s, NOT NEW ONES. A page running both this
+  package and the component library should not show two radius scales a few pixels
+  apart, and taking theirs is how that is guaranteed rather than kept in step by
+  hand. `--wave-docs-radius-base` is the override point: a host writes
+  `--wave-docs-radius-base: var(--radius)` and every corner here follows their app,
+  including any theme that moves it. Overriding three tokens separately would be
+  three chances to break the arithmetic below.
+
+  ⚠️ `--wave-docs-radius-step` IS LOAD-BEARING. The panel's inset surface takes the
+  base radius and its frame takes `-lg`, which is the base plus one step — so the
+  two corners are concentric only while the frame's _padding_ is that same step.
+  It is paid out of the token rather than written as `4px`, so moving the root
+  keeps both true. `--wave-docs-radius-panel` is gone with it: a token whose only
+  job is to be another token minus a constant is a number that can drift from its
+  own definition.
+
+  ## Squircles, where the browser has them
+
+  `corner-shape` renders every `border-radius` as a continuous superellipse rather
+  than a circular arc. `@waveso/ui` ships it and this now matches, including the
+  root bump both make under the same `@supports` — a squircle reads tighter at the
+  same radius, so the scale moves up to restore the roundness the numbers were
+  chosen for. Only the root moves; every tier and the panel's padding follow.
+
+  ⚠️ 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 trespass as claiming `html` or `body`, which this file already refuses.
+  Pills and dots opt back out, because a squircled pill is a lozenge.
+
+  ⚠️ AND THE SOURCE TEST FOR THE CONCENTRIC ARITHMETIC WENT VACUOUS ON THE WAY.
+  It regexed three `rem` literals out of the token block; with the tiers as
+  `calc()` the regex matched nothing, both sides defaulted to zero, and `0 - 0`
+  passed while asserting nothing. It is measured in computed pixels now, which is
+  also the only tier that can see the squircle bump. Two browser assertions that
+  built an expected radius out of `getPropertyValue` were the same mistake in a
+  different shape — a custom property is not computed to pixels, so it hands back
+  the `calc()` as written. They compare two computed corners to each other now,
+  which is the uniformity claim anyway.
+
+### Patch Changes
+
+- 04b7de7: **A blockquote is a box, not a rule down one edge.**
+
+  Every other block set apart from the prose here — a callout, a code frame, a
+  table, an embed — is a bordered box. A single 3px edge made the quote the one
+  exception, so next to a callout two paragraphs away it read as a _different kind
+  of thing_ rather than as a quieter one.
+
+  It is the callout's box now, minus the hue: the same padding so their text lines
+  up, the 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 it
+  finally looks like it.
+
+  Still 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 rather than only for speech.
+
+  ⚠️ AND IT HAD TO JOIN THE SQUIRCLE LIST BY NAME. Corner shaping is scoped to
+  elements this package owns, matched by our own class prefix — and a `blockquote`
+  is the markdown author's tag, with no class of ours on it. It would have been
+  the one block on the page still drawing a circular arc.
+
+- 975acba: **A callout draws one uniform border, not a 3px rule down its inline start.**
+
+  The stripe made a callout the exception among blocks set apart from the prose —
+  a code frame, a table, an embed and now a blockquote are all boxes with one
+  border all the way round — so beside any of them it read as a different kind of
+  thing rather than as a coloured one. A thick rule on one side also fights the
+  corner it runs into once the box is a squircle.
+
+  ⚠️ 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 stay as
+  reinforcement rather than as the whole message.
+
+  The table-of-contents rail keeps its 2px inline-start border. That is a
+  continuous line an active marker slides along, which is a navigation affordance
+  rather than the edge of a box, and a source guard names the two blocks it does
+  apply to.
+
+- cd21631: **The copy button draws Lucide icons, like everything else here.**
+
+  It rendered `⧉`, and swapped in `✓` and `×` through CSS `content` — three
+  characters drawn by whatever font resolved, at whatever weight and baseline
+  that font has, beside a sidebar, a pager, a callout and a search dialog that
+  are all Lucide paths at `stroke-width: 2`. It read as a different icon set
+  because it was one. Now `copy`, `check` and `x` on the same 24×24 grid.
+
+  ⚠️ THE SWAP IS `display` AND NOT `visibility`, AND THAT IS NOT A PREFERENCE.
+  All three icons ship in the markup and the stylesheet picks one — there is no
+  component owning this button, so there is no state to re-render. But the button
+  is `visibility: hidden` until the runtime attaches, which is what keeps a reader
+  with no JavaScript from meeting a control that does nothing and keeps it out of
+  the tab order — and `visibility` inherits. An icon rule setting it back to
+  `visible` would draw a glyph inside a button that is meant to be invisible.
+  `display` does not inherit, so the button's own rule still governs all three.
+
+  Three icons per fence is fifty on a page with fifty of them, and the repeat is
+  why that is affordable: byte-identical every time, which is the case gzip
+  handles best. The quick start's gzipped payload did not move, and the
+  hast-over-the-wire ratio for code and tables went from 1.11× to 1.09×.
+
+  ## And it stops drawing a box around itself
+
+  No border and no ground, in any state. A bordered, filled 2rem box sitting 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, and hover moves its ink to the accent rather than putting a box behind
+  it — the same signal every other interactive surface here gives. A ground also
+  had nowhere to come from: the subtle ramp _is_ the frame's colour, so the hover
+  state it used to have was the colour the button was already sitting on.
+
+  ⚠️ AND IT HAD NO FOCUS INDICATOR AT ALL, WHICH THE BORDER WAS COVERING FOR. A
+  1px box 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 it never appeared in the package's own inventory of focusable
+  surfaces. Taking the border away made that visible; it did not create it. There
+  is a real `:focus-visible` outline now, and a test that keeps it.
+
+  ⚠️ AND ONE TEST WAS PASSING BY ACCIDENT. `render.test.ts` asserted that a
+  GitHub alert produces no octicons by checking the _whole document_ for `<svg>`,
+  which was only ever true because nothing else in the pipeline emitted one. It
+  now checks the callout's own subtree, which is what it meant.
+
+- d7333cb: **The site's pages stop hand-writing their own "Next" link.** Nineteen of them
+  ended with `Next: [Page](./page.md).`, which the pager has rendered from the
+  navigation tree since it landed — the same link, twice, a few hundred pixels
+  apart, and the hand-written one silently wrong the moment a page moved in the
+  tree.
+
+  Documentation-only: no package change.
+
+- 6f0afb7: **A panel title is the size of a column header.**
+
+  "Where to go next" and `Enforced by` are the same kind of thing — the label a
+  reader's eye lands on before the content under it — and a page shows both. At
+  `0.875rem` against the table's `0.9375rem` they read as two levels rather than
+  as one.
+
+  The weight does not follow: a panel title names the block, a column header names
+  a column inside one, so the title stays a step heavier. A source guard pins the
+  pair, because two literals that have to agree are two literals that drift.
+
+- 8c59155: The navigation stops being lopsided.
+
+  Its rows sat 16px from the inline start and 31px from the end. The 15px was
+  `scrollbar-gutter: stable`, which reserves the scrollbar's width whether or not
+  it is showing — and that reservation sits _inside_ the padding.
+
+  The jump it prevents is one 15px shift, the first time a nav grows past a
+  screen. What it cost was permanent and on every page.
+
+  ⚠️ AND IT IS A NO-OP ON macOS, WHICH IS WHY IT SURVIVED BEING LOOKED AT.
+  `scrollbar-gutter` does nothing where overlay scrollbars are the default, so the
+  asymmetry was invisible to everyone who built this and plain on every Windows
+  and Linux machine that opened it.
+
+  `scrollbar-width: thin` in its place, with `scrollbar-color`, so the scrollbar
+  that does appear is narrow and coloured rather than a UA slab against the
+  panel's edge. A browser test measures both insets and fails at 15px.
+
+- e94bb67: **A table keeps one frame, at the panel's radius.**
+
+  It wore `.wave-docs-panel` for a while — outer frame, header band, inset card —
+  and that was wrong for a reason worth writing down rather than just undoing.
+
+  ⚠️ THE PANEL SEPARATES _CHROME_ FROM _CONTENT_, AND A TABLE'S HEADER ROW IS
+  CONTENT. "Where to go next" and a code frame both have chrome to put in the
+  band: a title, a language, a copy button. A table's `<thead>` is data. Setting
+  the body into a card away from its own header cost three vertical rules down
+  each side, stopped the row dividers short of the box and narrowed the reading
+  width — on the densest element on a page, for nothing gained. Full-width
+  dividers are what let an eye track a row across.
+
+  What is kept is the outer radius: `--wave-docs-radius-lg` rather than
+  `--wave-docs-radius`, so a table and a code block read as two of one family
+  without the table pretending to chrome it has not got.
+
+  ⚠️ AND AN EMPTY HEADER ROW NOW DRAWS NO BAND, WHICH GFM PRODUCES ROUTINELY. A
+  GFM table always has a `<thead>` — the delimiter row is what makes it a table —
+  so an author who wants a plain two-column list of facts writes `| | |` and gets
+  a header of empty `<th>`s, which rendered as a tinted strip with nothing in it.
+  `:empty` and not a text check: GFM emits `<th></th>` with no whitespace inside.
+  A header with even one named column keeps its band.
+
+  **And a fence with neither a title nor a language gets no band either.** The
+  header row is floored so titled and untitled fences match, which is right when
+  there is a label and wrong when there is not: a bare fence had only the copy
+  button, adrift in a strip of empty ground. The row is the button now.
+
 ## 0.10.0
 
 ### Minor Changes