@waveso/docs 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # @waveso/docs
 
+## 0.7.0
+
+### Minor Changes
+
+- da25315: **A page becomes a landing page by declaring its actions.** `actions` in the
+  frontmatter turns `title` and `description` into a page header with those links
+  beneath them:
+
+  ```yaml
+  ---
+  title: Wave Docs
+  description: Markdown documentation for Next.js.
+  actions:
+    - label: Quick start
+      href: /getting-started
+    - label: GitHub
+      href: https://github.com/waveso/docs
+      variant: secondary
+  ---
+  ```
+
+  Leave it off and the page is exactly what it was: `description` stays a `<meta>`
+  tag and the title is the first thing in the prose. That is the whole of the
+  adaptation for the two shapes this package serves — documentation that is the
+  entire site puts a hero on its index, and documentation mounted at `/docs`
+  inside an application that already has a marketing page leaves `actions` off.
+  There is no mode, no `standalone` flag and nothing to configure.
+
+  Actions are primary-then-secondary by position, so the common case needs no
+  `variant`. Anything that leaves the site gets a plain `<a>` rather than the
+  router link, plus `target`, `rel` and a screen-reader suffix; `mailto:` and
+  `tel:` get none of that, because they open no tab. Unsafe hrefs fail the build
+  rather than reaching an `<a>` — frontmatter was the one door into an `href` that
+  bypassed `isSafeHref`.
+
+  `DocsHero` is exported at `@waveso/docs/react/hero`, and `DocAction` from
+  `@waveso/docs/types`.
+
+  ⚠️ A HERO PAGE MUST NOT ALSO WRITE ITS OWN `# Title`. `render` normally prepends
+  an `<h1>` from `frontmatter.title`; on a hero page the hero renders that heading
+  instead, because the tagline and the actions have to sit beneath it. Writing one
+  in the body as well ships two `h1`s — the same duplication `titleHeading` has
+  always warned about.
+
+  The background is a rotated line grid drawn with `repeating-linear-gradient`
+  rather than an inlined SVG: no data URI in the stylesheet, and the lines are
+  `--wave-docs-hero-grid` and `--wave-docs-hero-grid-strong` — Wave 200 and Wave
+  300 from `@waveso/ui` in the light theme, Wave 900 and Wave 800 in the dark one
+  — so they follow the theme. They are tokens of their own rather than the border
+  colours, because a decorative tint must not be tied to a functional contrast
+  ratio.
+
+- 915729f: **`docs.Layout` renders no header, and the navigation is one sidebar at every
+  width.** A full-width sticky bar is the one element that competes with a host
+  application's own for the viewport's top edge, and two of the sites using this
+  have one — measured against a fixed 64px host bar, ours landed on top of theirs
+  at every width. The chrome it held lives in the sidebar now:
+
+  ```
+  .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            a 44px strip — paints nothing at rest
+     ├─ .wave-docs-layout__sidebar-scrim
+     ├─ .wave-docs-layout__main
+     └─ .wave-docs-layout__toc
+  ```
+
+  Pressing the trigger translates the sidebar by exactly the navigation's width,
+  so it leaves the page entirely and the trigger's outer edge lands on the inline
+  start edge. There is no drawer, no `<dialog>`, no second control and no second
+  copy of the tree.
+
+  **Nothing this package renders is anchored to the viewport.** The sidebar is a
+  grid item, the trigger is a flex child of it, and the scrim is `absolute` inside
+  `.wave-docs-layout` — so every one of them resolves against a box this package
+  owns and _your_ layout placed. `position: fixed` is the thing to avoid, and the
+  reason is specific: a fixed element is anchored to the viewport you share with
+  it, your navbar is in the same viewport, and neither can detect the other. The
+  search dialog is the one exception and always was.
+
+  **There is not one width-based `@media` query left.** Every breakpoint is
+  `@container`. `@media` asks how wide the _screen_ is, which is the wrong
+  question for a package mounted at `/docs` inside an application that owns the
+  rest of the page: put this in a 700px panel on a 1920px monitor and `@media`
+  says "wide", the sidebar takes its 16rem column, and the reading column comes
+  out around 60px. Two shapes fall out of the container width — beside the
+  article, or over it behind a scrim with `inert`, Escape, click-to-dismiss and
+  focus moved in and restored.
+
+  Migration, in full:
+
+  | Was                                                           | Becomes                                                |
+  | ------------------------------------------------------------- | ------------------------------------------------------ |
+  | `<docs.Layout title={<Brand/>}>`                              | Delete it. The index page's title brands the docs      |
+  | `<docs.Layout actions={<ThemeToggle/>}>`                      | Render it in your own layout, around `docs.Layout`     |
+  | `--wave-docs-header-height` set so sticky columns clear a bar | `--wave-docs-chrome-offset`, same value                |
+  | `--wave-docs-header-height` set to size the bar               | Nothing sizes a bar. There is no bar                   |
+  | `--wave-docs-shell-width` set to cap the shell                | Nothing. `--wave-docs-measure` caps the reading column |
+  | `actions` as the client-search escape hatch                   | `search={false}` plus your own `DocsSearch`            |
+  | A `rootMargin` you relied on defaulting to `-80px`            | Pass it explicitly                                     |
+  | `.wave-docs-layout__header` / `__title` / `__actions`         | Not rendered                                           |
+  | `.wave-docs-layout__sidebar > .wave-docs-sidebar`             | The tree is a grandchild now                           |
+
+  ⚠️ `--wave-docs-header-height` DID TWO JOBS AND ONLY ONE SURVIVES. It sized the
+  header, and it was the offset both sticky columns parked below. Nothing of this
+  package's sits above the content any more, so the sizing job is gone; the offset
+  job is `--wave-docs-chrome-offset`, and a host with their own fixed bar still
+  needs to set it or the sidebar and the table of contents park underneath it.
+
+  ⚠️ `--wave-docs-chrome-offset` DEFAULTS TO `0rem`, WITH A UNIT, AND THE UNIT IS
+  LOAD-BEARING. It is read inside `calc(100dvh - …)`, where a unitless `0` is
+  invalid at computed-value time — the height on the sidebar and the `max-height`
+  on the table of contents would die rather than resolve to no change.
+
+  ⚠️ `--wave-docs-shell-width` IS GONE RATHER THAN RENAMED. It capped the whole
+  shell and centred it, which pushed the sidebar's inline start 480px in from the
+  screen on a 2560px display — and left a _closed_ navigation parked in the
+  centring margin instead of off the page. The sidebar owns the page's inline
+  start edge at every width now, which is what makes "closed" mean off the screen
+  by construction, and the reading column is what is capped.
+
+  `DocsToc`'s `rootMargin` default changes from `'-80px 0px -60% 0px'` to
+  `'0px 0px -60% 0px'`. The 80px reserved room for a sticky header that is no
+  longer rendered; a host whose own chrome overlays the content passes the prop.
+
+  `DocsLayoutProps` is three props — `children`, `search` and `labels`.
+
+  Two behaviours are lost with the drawer and are worth knowing: the navigation no
+  longer opens before hydration (it was a server-rendered
+  `<button command="show-modal">`), and the client bundle grows about 500 bytes
+  for the containment work `<dialog>` used to give for free.
+
+### Patch Changes
+
+- 1313e77: The shell no longer depends on the host shipping a CSS reset.
+
+  ⚠️ `box-sizing` WAS THE HOST'S TO SET, AND ALMOST EVERY HOST SETS IT.
+  `.wave-docs-sidebar__link` is `width: 100%` with `0.5rem` of inline padding, so
+  under `content-box` it is a 272px box in a 256px track — and the external-link
+  icon that `justify-content: space-between` pins to the far end renders 8px
+  outside the sidebar, clipped in half. Tailwind's preflight and every
+  normalize-style reset declare `border-box` globally, so this was invisible in
+  every project that has one, and visible on the only site here that ships no CSS
+  at all. `box-sizing: border-box` now applies to elements carrying a
+  `wave-docs-` class, scoped to this package's own namespace rather than to `*`,
+  because the prose renders a consumer's components too.
+
+  Three README claims were wrong and are corrected: `react/*` is ten subpaths and
+  not nine, three modules import from `next/*` and not two, and the twenty-two
+  chrome labels break down into six groups rather than the five that summed to
+  nineteen.
+
 ## 0.6.0
 
 ### Minor Changes
@@ -404,7 +558,7 @@
 
   Every subpath in `exports` is listed in the README, and so is every runtime name each one exports — `manifest.test.ts` enumerates both against the built output and fails the build on a name this README does not mention. That test is new in this release, and writing it immediately found five: `DOCS_ERROR_PREFIX`, `DEFAULT_DOCS_THEMES`, `CALLOUT_TYPES`, `defaultMarkdownComponents` and `DOCS_CONTENT_ID` were all public and documented nowhere.
 
-  **The default page is worth looking at.** A 46rem measure and a system font stack, a 1.2 minor-third type scale, tables that scroll instead of shredding the layout, one focus `outline` in place of five `box-shadow` rings (which also deletes the forced-colors block that existed to patch them), and a responsive shell with breakpoints at 64/80/100rem. The element tree, the five layout tokens and the breakpoints are frozen in `docs/adr/001-shell-contract.md`.
+  **The default page is worth looking at.** A 46rem measure and a system font stack, a 1.2 minor-third type scale, tables that scroll instead of shredding the layout, one focus `outline` in place of five `box-shadow` rings (which also deletes the forced-colors block that existed to patch them), and a responsive shell with breakpoints at 64/80/100rem. The element tree, the five layout tokens and the breakpoints are frozen.
 
   **Three new harnesses, because the old ones could not see these failures.** A browser tier running real Chromium — jsdom reports every width as `0`, so the measure, the type scale, reflow and the table floor were unassertable. A smoke build of a real Next application against the published `exports` map, in both output modes. And `pnpm check:readme`, which type-checks every example in this README as one project: it immediately found `app/docs/layout.tsx` defined twice with different bodies, and an `imageResolver` example calling `imageSize(path)` when `image-size` v2 takes a `Uint8Array`.
 

package/README.md

@@ -69,16 +69,16 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | At most |
 | --- | --- |
-| Everything the quick start ships, gzipped | 13.5 KB |
+| Everything the quick start ships, gzipped | 13.9 KB |
 | Search dialog and router wiring | 9.3 KB |
-| Navigation: sidebar and mobile drawer | 2.4 KB |
+| Navigation: one sidebar, open and closed | 2.9 KB |
 | Table of contents | 0.9 KB |
 | Copy-button runtime | 1.1 KB |
 | hast over the wire vs HTML, prose page | 1.20× |
 | hast over the wire vs HTML, code and tables | 1.12× |
 | Highlighting vs no highlighting | 2.00× |
 
-The first row is the honest total: a reader who lands on a page of your documentation downloads under 13.5 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
+The first row is the honest total: a reader who lands on a page of your documentation downloads under 13.9 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
 
 The one real cost is the middle pair: shipping a tree instead of a string is about 20% more brotli on a prose page, and about 12% on a page with code and tables, where Shiki's token spans dominate both representations equally. That is the price of never handing markup to `dangerouslySetInnerHTML`, and it is the first number a skeptical reviewer should ask for.
 
@@ -140,7 +140,7 @@ content/docs/
     authentication.md
 ```
 
-That is a working documentation site: routing, a navigation sidebar, a table of contents, syntax highlighting, search, a mobile drawer and a skip link.
+That is a working documentation site: routing, a navigation sidebar that opens and closes, a table of contents, syntax highlighting, search and a skip link.
 
 The search route is in the quick start rather than in a section further down because `docs.Layout` renders the search trigger by default — leave the route out and a reader gets a control that opens onto "Search is unavailable". If you genuinely do not want search, `export default function Layout(props) { return docs.Layout({ ...props, search: false }) }` drops both the trigger and this file. See [Search](#search) for tuning.
 
@@ -158,7 +158,7 @@ There is no root export. Every entry point is a subpath, so an import always nam
 | `@waveso/docs/render` | Node | `createDocsRenderer`, `resolveMarkdownLink` |
 | `@waveso/docs/highlighter` | Node | `createDocsHighlighter`, `DEFAULT_DOCS_LANGS`, `DEFAULT_DOCS_THEMES` |
 | `@waveso/docs/search-index` | Node | `extractSearchRecords`, `buildSearchIndex` |
-| `@waveso/docs/react/<name>` | Browser + RSC | Nine components, one per subpath — see [Components](#components) |
+| `@waveso/docs/react/<name>` | Browser + RSC | Ten subpaths, one component each — see [Components](#components) |
 | `@waveso/docs/frontmatter` | Any | `docFrontmatterSchema`, `parseFrontmatter`, `z` |
 | `@waveso/docs/types` | Any | Every shared type. Type-only |
 | `@waveso/docs/errors` | Any | `DocsErrorCode`, `DocsError`, `isDocsError`, `DOCS_ERROR_PREFIX` |
@@ -172,15 +172,21 @@ That is about **weight, not about `node:fs`** — and the distinction matters, b
 
 ### Layout tokens
 
-Five custom properties size the shell, all layered so an unlayered `:root` of your own still wins. The full contract is in [`docs/adr/001-shell-contract.md`](./docs/adr/001-shell-contract.md).
+Five custom properties size the shell, all layered so an unlayered `:root` of your own still wins. All six are public API: a name changes only in a release that carries the migration.
 
 | Token | Default | Controls |
 | --- | --- | --- |
 | `--wave-docs-measure` | `46rem` | Prose column width. `none` opts out |
-| `--wave-docs-header-height` | `3.5rem` | Header, and the offset sticky columns park below |
-| `--wave-docs-sidebar-width` | `16rem` | Sidebar track |
+| `--wave-docs-sidebar-width` | `16rem` | The navigation's width |
+| `--wave-docs-trigger-width` | `1.25rem` | The trigger's button. The strip around it is this plus 4px a side |
 | `--wave-docs-toc-width` | `15rem` | Table-of-contents track |
-| `--wave-docs-shell-width` | `100rem` | Maximum shell width |
+| `--wave-docs-chrome-offset` | `0rem` | Where our sticky chrome starts, below a bar of yours |
+
+**`--wave-docs-shell-width` was removed in 0.7.0, and it is the sidebar's edge that replaced it.** It capped the whole shell and centred it, which put the sidebar's inline start 480px in from the screen on a 2560px display — and, worse, left a *closed* navigation parked in the centring margin instead of off the page. The reading column is the thing that should not stretch, so `--wave-docs-measure` caps it and it centres itself in its track; the sidebar keeps the page's inline start edge at every width, which is what makes "closed" mean off the screen by construction.
+
+**`--wave-docs-header-height` is gone in 0.7.0, and renaming it to one thing would have lost the other.** It sized the header *and* it was the offset both sticky columns parked below. The header is gone, and so is every shape that sat above the content, so the sizing half has nothing left to size. The offset half is the one that matters and it is `--wave-docs-chrome-offset`: `--wave-docs-chrome-offset: 4rem` starts our sidebar and our table of contents 4rem down, and feeds the scroll padding that keeps an anchored heading clear of your bar.
+
+The default is `0rem` rather than `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 kills the `max-height` instead of resolving to no change.
 
 The shell has three breakpoints, in `rem` so they scale with the reader's base font size: the sidebar appears at **64rem**, the table of contents at **80rem**, and the whole grid stops growing at **100rem**. 64rem is arithmetic rather than taste — a 16rem sidebar plus a 46rem measure plus two 1.5rem gutters is 65rem, so anything narrower introduces the sidebar exactly where it starts eating the measure it frames.
 
@@ -190,11 +196,12 @@ Every subpath is enumerated in `exports` — there is no wildcard. A name that i
 
 ## Components
 
-Every component takes data as props, and two modules in `src/react/` import from `next/*` — `next-nav` for `usePathname` and `next-search` for `useRouter`, each named so the exception is visible in the file list. Everything else has `next/link` and `next/image` injected. That keeps the renderer host-agnostic and testable without a router. `DocsSearch` is the one exception, and it exists precisely so that the exception is ours rather than yours: it is the fifteen-line wrapper you would otherwise write around `SearchDialog`.
+Every component takes data as props, and every module that imports from `next/*` is named for it — `next-nav` for `usePathname`, `next-search` for `useRouter`, `next-link` for `next/link` itself — so the exception is visible in the file list rather than three imports deep. Everything else has `next/link` and `next/image` injected. That keeps the renderer host-agnostic and testable without a router. `DocsSearch` is the one exception, and it exists precisely so that the exception is ours rather than yours: it is the fifteen-line wrapper you would otherwise write around `SearchDialog`.
 
 | Component | Subpath | Notes |
 | --- | --- | --- |
 | `DocContent` | `react/doc-content` | Renders a hast tree, inside `.wave-docs-prose`. Server Component |
+| `DocsHero` | `react/hero` | A landing page's header. `title`, `description`, `actions`, `Link`, `externalLabel`. Server Component |
 | `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
@@ -211,47 +218,101 @@ The two components the adapter injects take a little more than an `<a>` and an `
 
 ### Layout
 
-`export default docs.Layout` — the one line from the [quick start](#quick-start) — is a Server Component that renders the whole shell: skip link, sticky header, sidebar column, mobile drawer, and the grid that arranges them. It reads the navigation tree and the search index URL itself, so there is nothing to fetch and nothing to pass.
+`export default docs.Layout` — the one line from the [quick start](#quick-start) — is a Server Component that renders the whole shell: skip link, sidebar, search trigger, and the grid that arranges them. It reads the navigation tree and the search index URL itself, so there is nothing to fetch and nothing to pass.
+
+**It renders no header, and that is deliberate.** Two kinds of site use this package: documentation mounted inside an application that already has a header, a navbar and its own search, and documentation that is the whole site. A full-width sticky bar of ours serves the second and fights the first — two stacked bars competing for the viewport's top edge, and two search boxes on one page, one of which knows nothing about the documentation.
+
+So the sidebar is the chrome. It is a real grid item at every width, and it is the same shell on a phone and on a desktop.
+
+**Nothing this package renders is anchored to the viewport.** The sidebar is a grid item, the trigger is a flex child of it, and the scrim is `position: absolute` inside `.wave-docs-layout` — so every one of them resolves against a box this package owns and *your* layout placed. `position: fixed` is the thing to avoid, and the reason is specific: a fixed element is anchored to the viewport you share with it, your navbar is in the same viewport, and neither can detect the other. The search dialog is the one exception and always was — top-layer, present only while open, and nothing collides with something that is not there.
 
 Your layout stays a Server Component. The two pieces that need a client — the navigation's `usePathname`, the search dialog — carry their own `'use client'` boundaries inside the package.
 
-To put your own chrome in the header, call it instead of re-exporting it:
+Your own chrome goes *around* `docs.Layout`, in the layout file you already write — the same place `<html>` and `<body>` live. Call it instead of re-exporting it when you want to wrap it, configure it, or both:
 
 ```tsx
 import type { ReactNode } from 'react';
 import '@waveso/docs/styles.css';
 import { docs } from '@/lib/docs';
 
+/** Yours: the header, theme toggle and repository link the rest of the site has. */
+declare function SiteHeader(): ReactNode;
+
 export default function DocsLayout({ children }: { children: ReactNode }) {
   return (
-    <docs.Layout
-      title="Wave"
-      actions={<a href="https://github.com/waveso/docs">GitHub</a>}
-    >
-      {children}
-    </docs.Layout>
+    <>
+      <SiteHeader />
+      <docs.Layout search={{ placeholder: 'Search the docs' }}>
+        {children}
+      </docs.Layout>
+    </>
   );
 }
 ```
 
+If that header of yours is sticky, say how tall it is once and the shell's sticky columns start below it:
+
+```css
+:root {
+  --wave-docs-chrome-offset: 4rem;
+}
+```
+
 | Prop | Type | Default | |
 | --- | --- | --- | --- |
-| `title` | `ReactNode` | — | Brand, at the header start |
-| `actions` | `ReactNode` | — | Header end, after search |
+| `children` | `ReactNode` | — | What `docs.Page` returns — the `<main>` and the TOC, as two siblings |
 | `search` | `boolean \| DocsSearchProps` | `true` | The search trigger. An object configures the dialog |
 | `labels` | `DocsLabels` | the route's | Overrides `createDocsRoute`'s labels, key by key |
 
-Five props, and two of them are small objects. That is deliberate, and it is the difference between this and an eleven-slot layout: everything else a docs shell gets asked for is already reachable. An announcement banner goes *above* `<docs.Layout>` in your own layout, because this does not own `<body>`. A content footer goes inside `children`. Sidebar links, social icons and separators are `DocNavNode`s you author in `meta.json`. The header bar was the one region nothing else could reach — hence `actions`. Two node props can become a slots map later; a slots map cannot become two props.
+Three props, and one of them is `children`. That is deliberate, and it is the difference between this and an eleven-slot layout: everything else a docs shell gets asked for is already reachable. An announcement banner goes *above* `<docs.Layout>` in your own layout, because this does not own `<body>`. A content footer goes inside `children`. Sidebar links, social icons and separators are `DocNavNode`s you author in `meta.json`. A theme toggle and a repository link go in the layout you write around this one.
+
+**`title` and `actions` were removed in 0.7.0, with the header they lived in.** `title` was a brand slot, and a brand belongs to the index page's own title — content, authored and translatable, part of what the reader came for. The argument for `actions` was that the header bar was the one region nothing else could reach; there is no header bar, and the host wraps `docs.Layout` exactly as it already wraps `<html>` and `<body>`, so there is no region only this package can reach. The one place a host cannot reach through this prop list is *inside* the sidebar, and the answer to that is [composing the primitives yourself](#composing-it-yourself).
 
 `search` takes anything `DocsSearch` takes except `indexUrl`, which stays derived from your `basePath`. You do not need to repeat `miniSearchOptions` here to match `createDocsRoute` — the route's own value is forwarded, so the object that built the index is the object that queries it.
 
 `labels` belongs on `createDocsRoute` — see [Translating the chrome](#translating-the-chrome) — and this prop overrides it key by key, for a site with two shells or a section in another language.
 
-#### The mobile drawer
+#### One sidebar, open and closed
+
+There is no mobile version. The sidebar is a shell holding two things in a row:
+
+```
+.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
+```
 
-Below 64rem the sidebar is a `<dialog>` opened by a server-rendered `<button command="show-modal">` — so it works on the first tap, before hydration, and with JavaScript disabled. Focus moves inside and Tab stays there, Escape closes it and returns focus to the trigger, a click on the backdrop dismisses it, and the page behind does not scroll. All of that is the browser's, not ours.
+Pressing the trigger translates the shell by `calc(var(--wave-docs-trigger-width) - 100%)` — "minus all of me, plus the trigger back" — so the navigation goes entirely off the page and the trigger's outer edge lands exactly on the inline start edge. **The navigation's width appears nowhere in that expression**, so the two cannot drift apart. The trigger rides on the navigation's outer edge because it is the next flex item, not because a number says so.
 
-At 64rem and above the same element becomes the sticky column, via `display: contents`. One navigation in the DOM at every width: one landmark, one copy of the links in the payload, nothing to keep in step.
+One navigation in the DOM at every width: one landmark, one copy of the links in the payload, nothing to keep in step.
+
+#### It adapts to its container, not to your screen
+
+**There is not one width-based `@media` query in this package.** Every breakpoint is `@container`, and that is not a stylistic preference — it is the difference between a docs theme and a component you can mount inside something else.
+
+`@media` asks how wide the *screen* is. If you put this in a 700px panel on a 1920px monitor, `@media` says "wide", the sidebar takes its 16rem column, and the reading column comes out around 60px. `@container` asks how wide the box you *gave* it is, which is the question with an answer.
+
+Two shapes fall out of that:
+
+- **Push**, in a container 64rem or wider: the navigation sits beside the article, and opening or closing it changes the article's width.
+- **Cover**, below that: the navigation sits on top of the article behind a scrim, and the article's measure never changes when you toggle.
+
+Same markup, same classes, same control, same translate. The only thing that differs is whether the article gets out of the way.
+
+Cover mode is a real overlay, so it ships what an overlay owes a reader: `inert` on everything the navigation covers, Escape to close, click-the-scrim to dismiss, and focus moving into the navigation and back out again. Those five were the browser's while this was a `<dialog>`; they are hand-written now, and skipping them is how an overlay becomes a keyboard trap in the wrong direction.
+
+`--wave-docs-sidebar-mode` is how the component knows which shape it is in: the stylesheet declares it, the component reads it back with `getComputedStyle`. `matchMedia` cannot answer a container query, and duplicating the breakpoint in JavaScript is how the two drift.
+
+#### Three states, and no flash
+
+The server renders no `data-state` at all. That absence means "nobody has chosen yet", and CSS resolves it 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 a reader presses the trigger their choice is explicit and wins at every width.
+
+**This replaced a `<dialog>` drawer in 0.7.0.** Below 64rem the navigation used to be a modal opened by a second control, with `display: contents` above it so the same DOM could serve as the desktop column. It bought focus trapping, Escape and a scroll lock from the browser, and it worked before hydration. It cost two controls for one piece of navigation, a drawer that painted over the tree it contained, and a scroll-into-view that could never run on a phone — a closed `<dialog>` has no layout, so the current page was always below the fold. A closed sidebar is *moved*, not hidden, so that last one is structurally impossible now.
 
 #### Composing it yourself
 
@@ -286,7 +347,7 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
 
 `docs.Page` returns exactly this shape: the `<main>` and the table of contents as **two siblings**, not one wrapped element. They land as direct children of the grid, which is what puts them in separate columns — so if you compose your own page inside `docs.Layout`, return a fragment rather than a wrapper.
 
-**The two class names are load-bearing**, and they are the part of this that is easy to leave off. `wave-docs-layout__main` carries `min-width: 0`, without which a wide table pushes the whole document into horizontal scroll (measured: 1048px of document inside a 1024px viewport). `wave-docs-layout__toc` is what the grid reserves its third track with, via `:has()` — unclassed, the table of contents auto-places into the next row underneath the sidebar above 80rem, and renders inline on a phone instead of being hidden. Both are frozen in [`docs/adr/001-shell-contract.md`](docs/adr/001-shell-contract.md), so they are safe to write by hand.
+**The two class names are load-bearing**, and they are the part of this that is easy to leave off. `wave-docs-layout__main` carries `min-width: 0`, without which a wide table pushes the whole document into horizontal scroll (measured: 1048px of document inside a 1024px viewport). `wave-docs-layout__toc` is what the grid reserves its third track with, via `:has()` — unclassed, the table of contents auto-places into the next row underneath the sidebar above 80rem, and renders inline on a phone instead of being hidden. Both names are public API and change only in a release that carries the migration, so they are safe to write by hand.
 
 The `null` is load-bearing too: `:has()` matches an empty `<aside>` exactly as well as a full one, so a page with no headings would give up 15rem to nothing.
 
@@ -300,6 +361,12 @@ label: Auth                       # sidebar label, when the title is too long
 draft: true                       # excluded from nav, search and static params
 order: 10                         # sort weight where there is no meta.json
 aliases: [old-auth, legacy/auth]  # former URLs → permanent redirects
+actions:                          # calls to action — and the opt-in for a hero
+  - label: Quick start
+    href: /getting-started
+  - label: GitHub
+    href: https://github.com/waveso/docs
+    variant: secondary
 ---
 ```
 
@@ -307,6 +374,18 @@ aliases: [old-auth, legacy/auth]  # former URLs → permanent redirects
 
 `draft` is deliberately **not** tied to `NODE_ENV`. Preview deployments are production builds, so branching on it would hide drafts in exactly the place reviewers look — drive `includeDrafts` from your own environment check instead.
 
+### The hero
+
+`actions` is the only thing that turns a page into a landing page. Declare it and `title` and `description` become a page header — a large heading, the description as a tagline under it, and these links beneath that. Leave it off and the page is exactly what it was: `description` stays a `<meta>` tag and the title is the first thing in the prose.
+
+Each action takes a `label`, an `href` and an optional `variant` of `primary` or `secondary`. Omit the variant and the first action is the primary and the rest are secondary, which is the shape every landing page has. An `href` that leaves the site gets `target="_blank"`, `rel="noreferrer"` and a screen-reader suffix; `mailto:` and `tel:` do not, because they open no tab. Unsafe hrefs fail the build rather than reaching an `<a>`.
+
+**That is the whole of the adaptation for the two shapes this package serves.** Documentation that is the entire site puts a hero on its index. Documentation mounted at `/docs` inside an application that already has a marketing page leaves `actions` off and gets an ordinary page. There is no mode, no `standalone` flag and nothing to configure — the opt-in lives in the file that wants it.
+
+⚠️ **A hero page must not also write its own `# Title`.** `render` normally prepends an `<h1>` from `frontmatter.title`; on a hero page the hero renders that heading instead, because the tagline and the actions have to sit beneath it. Writing one in the body as well ships two `h1`s — the same duplication `titleHeading` has always warned about.
+
+The background is a rotated line grid under scrims painted in the page's own colour rather than behind a mask: a soft ellipse over the words, a bottom fade, and a vignette that closes at the corners. The vignette is an inset `box-shadow` rather than a gradient — a `radial-gradient` is only ever a circle or an ellipse, and this one needs a corner radius. `border-radius` is that knob, and `corner-shape: superellipse(3)` makes it a squircle where the browser supports it. Alpha compositing of a solid blends where mask layers multiply, so the falloff is smooth instead of compounding into a shoulder. It is drawn with `repeating-linear-gradient` rather than an inlined SVG — no data URI in the stylesheet. The lines are `--wave-docs-hero-grid` and `--wave-docs-hero-grid-strong`, which are Wave 200 and Wave 300 from `@waveso/ui` in the light theme and Wave 900 and Wave 800 in the dark one. They are tokens of their own rather than the border colours: the grid is decoration behind a mask that leaves it near-invisible where the words are, and a border is a boundary a reader has to be able to see.
+
 ### Your own fields
 
 Pass a `frontmatterSchema` and every `DocFile` and `RenderedDoc` carries your fields, inferred, with no type argument anywhere:
@@ -715,7 +794,7 @@ export function DocsSearchTrigger({ indexUrl }: { indexUrl: string }) {
 }
 ```
 
-Add the same function to your `createDocsRoute` call — `miniSearchOptions: { processTerm: stripDashes }` — so the index is built with it. Then turn the built-in trigger off and render yours in `actions`, in `app/docs/layout.tsx`:
+Add the same function to your `createDocsRoute` call — `miniSearchOptions: { processTerm: stripDashes }` — so the index is built with it. Then turn the built-in trigger off and render yours in the layout you write around `docs.Layout`, in `app/docs/layout.tsx`:
 
 ```tsx
 import '@waveso/docs/styles.css';
@@ -725,17 +804,15 @@ import { docs } from '@/lib/docs';
 
 export default function DocsLayout({ children }: { children: ReactNode }) {
   return (
-    <docs.Layout
-      search={false}
-      actions={<DocsSearchTrigger indexUrl={docs.searchIndexUrl} />}
-    >
-      {children}
-    </docs.Layout>
+    <>
+      <DocsSearchTrigger indexUrl={docs.searchIndexUrl} />
+      <docs.Layout search={false}>{children}</docs.Layout>
+    </>
   );
 }
 ```
 
-`search={false}` omits the built-in trigger so yours is the only one, and it is also why the refusal is scoped to the forward: the route keeps the function for the index it builds on the server, and nothing crosses to the client but a string.
+`search={false}` omits the built-in trigger so yours is the only one, and it is also why the refusal is scoped to the forward: the route keeps the function for the index it builds on the server, and nothing crosses to the client but a string. To put your trigger *inside* the sidebar rather than above it, [compose the shell yourself](#composing-it-yourself) — `docs.Layout` has no slot for it, deliberately.
 
 ### Building the index yourself
 
@@ -849,7 +926,7 @@ A link is skipped when it equals one of these or begins with one followed by `/`
 
 ### Translating the chrome
 
-Twenty-two strings, and every one of them is yours to set. They go on `createDocsRoute` rather than on `docs.Layout`, because they are not all rendered in the same place: four are the shell's, two the table of contents', nine come from the markdown component map, two are baked into the HTML by a rehype plugin at build time, and two are announced by a client-side runtime after a copy. A layout prop is upstream of the first four and nothing else.
+Twenty-two strings, and every one of them is yours to set. They go on `createDocsRoute` rather than on `docs.Layout`, because they are not all rendered in the same place: four are the shell's, three the navigation tree's, two the table of contents', nine come from the markdown component map, two are baked into the HTML by a rehype plugin at build time, and two are announced by a client-side runtime after a copy. A layout prop is upstream of the first four and nothing else.
 
 ```ts
 // lib/docs-pt.ts
@@ -1051,9 +1128,9 @@ breaking — which is the part most packages leave unsaid until someone is angry
 | --- | --- |
 | Every subpath in `exports`, and every runtime name it exports | ✅ enforced by `manifest.test.ts` |
 | Exported types, including `DocsErrorCode`'s members | ✅ enforced by `error-taxonomy.test.ts` |
-| **CSS class names** — `wave-docs-*`, and the shell's element tree | ✅ frozen in [ADR 001](docs/adr/001-shell-contract.md) |
+| **CSS class names** — `wave-docs-*`, and the shell's element tree | ✅ a name changes only in a release that carries the migration |
 | **The hast this emits** — element names, and the attributes on them | ✅ the same policy as the types |
-| Layout tokens — the five custom properties above | ✅ |
+| Layout tokens — the six custom properties above | ✅ |
 | Anything reachable only through `dist/` internals, or a private module | ❌ |
 
 The two in bold are the ones usually omitted, and omitting them is how a
@@ -1147,7 +1224,7 @@ src/
   next.ts             # The App Router adapter
   meta.ts             # meta.json ordering
   plugins/            # remark/rehype plugins
-  react/              # Components. Only next-nav and next-search touch next/*
+  react/              # Components. Only the next-* modules touch next/*
   styles.css          # Theme tokens + prose styles
 ```
 

package/dist/frontmatter.d.ts

@@ -32,6 +32,14 @@ declare const docFrontmatterSchema: z.ZodObject<{
   draft: z.ZodExactOptional<z.ZodBoolean>;
   aliases: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
   order: z.ZodExactOptional<z.ZodNumber>;
+  actions: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+    label: z.ZodString;
+    href: z.ZodString;
+    variant: z.ZodExactOptional<z.ZodEnum<{
+      primary: "primary";
+      secondary: "secondary";
+    }>>;
+  }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
  * Validate one file's frontmatter, or throw an error that names the file.

package/dist/frontmatter.js

@@ -1,4 +1,5 @@
 import { docsError } from "./docs-error.js";
+import { isSafeHref } from "./safe-href.js";
 import { z } from "zod";
 //#region src/frontmatter.ts
 /**
@@ -30,7 +31,12 @@ const docFrontmatterSchema = z.object({
 	label: z.string().exactOptional(),
 	draft: z.boolean().exactOptional(),
 	aliases: z.array(z.string()).exactOptional(),
-	order: z.number().exactOptional()
+	order: z.number().exactOptional(),
+	actions: z.array(z.object({
+		label: z.string().min(1),
+		href: z.string().min(1).refine(isSafeHref, "must be a safe URL (no javascript: or data:)"),
+		variant: z.enum(["primary", "secondary"]).exactOptional()
+	})).exactOptional()
 });
 /**
 * The package's own fields, every one of them optional, for the overlay pass

package/dist/next.d.ts

@@ -96,27 +96,25 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
 /**
  * Props for {@link DocsRoute.Layout}.
  *
- * Four, and the fourth is a boolean. Everything else a docs shell is asked for
- * turned out to be reachable already: an announcement banner renders *above*
- * `<docs.Layout>` in your own `layout.tsx`, because this does not own `<body>`;
- * a content footer goes inside `children`; and sidebar links, social icons and
- * separators are `DocNavNode`s authored in `meta.json`. The header bar is the
- * one region nothing else can reach, which is what `actions` is for.
+ * Three, and one of them is `children`. Everything else a docs shell is asked
+ * for turned out to be reachable already: an announcement banner renders
+ * *above* `<docs.Layout>` in your own `layout.tsx`, because this does not own
+ * `<body>`; a content footer goes inside `children`; and sidebar links, social
+ * icons and separators are `DocNavNode`s authored in `meta.json`. A theme
+ * toggle and a repository link go in the layout you write around this one — the
+ * host wraps `docs.Layout` exactly as it already wraps `<html>` and `<body>`,
+ * so there is no region only this package can reach.
  *
- * A `slots` map was the alternative, and it can still be added later — two node
- * props can become a slots map, a slots map cannot become two props.
+ * The one region a host cannot reach through `docs.Layout` is *inside* the
+ * sidebar, and the exported primitives are the answer for that: `DocsSidebar`,
+ * `DocsToc`, `DocContent` and `SkipLink` compose into a layout of your own.
+ *
+ * A `slots` map was the alternative, and shipping none is the reversible half —
+ * a map can be added the day something needs one, a map that shipped cannot be
+ * taken back.
  */
 interface DocsLayoutProps {
   children: ReactNode;
-  /**
-   * Brand at the header start. A string, or your own logo component.
-   *
-   * `ReactNode`, so it cannot also serve as the `<title>` or as the header's
-   * accessible name; the landmark carries a fixed label instead.
-   */
-  title?: ReactNode;
-  /** Header end, after search: a theme toggle, a version switcher, a link. */
-  actions?: ReactNode;
   /**
    * The search trigger. Defaults to on, and the URL is always derived.
    *
@@ -318,24 +316,33 @@ interface DocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    * export default docs.Layout;
    * ```
    *
-   * Or, with your own chrome in the header:
+   * Or, with your own chrome *around* it — the same layout file `<html>` and
+   * `<body>` live in, and `SiteHeader` is yours:
    *
    * ```tsx
    * export default function DocsLayout({ children }: { children: ReactNode }) {
    *   return (
-   *     <docs.Layout title={<Logo />} actions={<ThemeToggle />}>
-   *       {children}
-   *     </docs.Layout>
+   *     <>
+   *       <SiteHeader />
+   *       <docs.Layout search={{ placeholder: 'Search the docs' }}>
+   *         {children}
+   *       </docs.Layout>
+   *     </>
    *   );
    * }
    * ```
    *
-   * It owns the skip link, the header, the sidebar column, the mobile drawer
-   * and the grid, and it reads `source.nav()` and `searchIndexUrl` itself — so
-   * there is no nav to fetch and no URL to pass. It does **not** own the table
-   * of contents: a Next layout receives `{children, params}` and cannot know
-   * which page is rendering, so `docs.Page` emits the TOC as its second child
-   * and the grid places it.
+   * If that header of yours is sticky, say how tall it is once —
+   * `--wave-docs-chrome-offset: 4rem` — and our sticky columns start below it.
+   *
+   * It owns the skip link, the sidebar — one shell at every width, holding the
+   * navigation and the 44px strip that moves it — the search trigger and the
+   * grid.
+   * It reads `source.nav()` and `searchIndexUrl` itself, so there is no nav to
+   * fetch and no URL to pass. It does **not** own the table of contents: a Next
+   * layout receives `{children, params}` and cannot know which page is
+   * rendering, so `docs.Page` emits the TOC as its second child and the grid
+   * places it.
    *
    * Your `layout.tsx` stays a Server Component. The two pieces that need a
    * client — the nav's `usePathname`, the search dialog — carry their own