@nanisoft/prism-ui 0.15.0 → 0.16.1

package/dist/pages/docs-shell/docs-shell.d.ts

@@ -15,15 +15,36 @@ import type { ReactNode } from 'react';
  * block used to make was true only of the group arm; it is now true of what the
  * Page renders, and it says which of the two is doing the work.
  *
- * `title` may be the empty string, and an entry with no words is not a page: it
- * renders as a label on the same rule that makes a group with no index a label,
- * and it is not a page the pager can reach either. A link with no accessible name
- * is announced as "link" and nothing else, which is the one thing a link in a
- * rail must never be.
+ * `title` may be the empty string, and an entry the Page cannot name is not
+ * rendered at all. It used to render as a label on the same rule that makes a
+ * group with no index a label, and that produced `<li><span></span></li>`: a
+ * row of nothing inside a `<nav>`, which one consumer measured at 102 across 25
+ * of its 31 documentation pages. A blank row is not a destination and it is not
+ * a label either, because a label is words. So the Page drops the entry and
+ * counts the drop on the rail as `data-unnamed-entries`, which is the same
+ * answer `Diagram` gives a relation it cannot resolve.
+ *
+ * **The page is not lost, and one thing is.** The address still resolves, the
+ * document still renders at it, and every link into it still works; what the rail
+ * loses is one row. The pager does lose that page, because the pager walks the
+ * same list and the row is no longer in it, so a reader who arrives at the address
+ * directly finds a document and no pager. That was already the answer before the
+ * row was dropped, and it is the cost of dropping rather than of this change:
+ * keeping it would mean publishing the nameless link a second time.
+ *
+ * **A blank `title` and a blank `href` are answered differently, and the reason
+ * is what each one has left.** A page with an address and no words is a real page
+ * with one unrenderable field, so dropping the row costs a reader nothing and
+ * taking the whole screen down over it would cost them everything. A page with
+ * words and no address is a row whose entire content is a route that does not
+ * exist, and there is nothing to render in its place, so `readTree` refuses it.
  */
 export type DocsNavPage = {
     type: 'page';
-    /** The words the reader meets. An empty string makes this a label, not a link. */
+    /**
+     * The words the reader meets. An empty or blank string names nothing, and the
+     * Page renders no row for the entry and counts the drop.
+     */
     title: string;
     /** The address the page is read at. An empty string is refused, by name. */
     href: string;
@@ -47,7 +68,15 @@ export type DocsNavPage = {
  */
 export type DocsNavGroup = {
     type: 'group';
-    /** The words on the label. A status inside them stays inside them. */
+    /**
+     * The words on the label. A status inside them stays inside them.
+     *
+     * An empty or blank string renders no label, and the pages under the group are
+     * still rendered: a group whose title cannot be rendered has lost a heading and
+     * not a section, so dropping the whole entry would delete pages the reader can
+     * otherwise reach. A group with no words and no children has nothing left to
+     * draw and is dropped whole.
+     */
     title: string;
     /**
      * The group's own index page, where it has one. Omit it for a group that is
@@ -259,21 +288,104 @@ export type DocsShellProps = {
  * author filed it. A Page that sorted its rail would flatten the one thing the
  * three sites disagree about and cannot both be right about.
  *
- * **The rail is bounded in height.** Atlas files nineteen pages and AlphaLens
- * files twenty-seven, so the taller tree is half again as long, and an unbounded
- * rail on a tall tree is a rail that pushes the document below the fold before
- * the reader has read a line of it. The rail and the contents rail are each
- * capped against the viewport and scroll inside it, so a nineteen-page tree and a
- * twenty-seven-page tree are both a full screen and neither is a page-long
- * sidebar.
+ * **The rail is bounded in height, and the bound is what the reader has to be
+ * able to see.** Atlas files nineteen pages and AlphaLens files twenty-seven, so
+ * the taller tree is half again as long, and an unbounded rail on a tall tree is
+ * a rail that pushes the document below the fold before the reader has read a
+ * line of it. The rail and the contents rail are each capped against the viewport
+ * and scroll inside it, so a nineteen-page tree and a twenty-seven-page tree are
+ * both a full screen and neither is a page-long sidebar.
+ *
+ * **A cap the reader cannot see is a defect, and this one was invisible for 344
+ * and 750 pixels.** Measured in two consumers' built exports at 1280 by 680, the
+ * rail's content stood at 912 and 1318 pixels against a 568 pixel box, so more
+ * than half of one site's documentation navigation sat below the fold with
+ * `mask-image: none`, no scrollbar Chrome would draw until the reader scrolled,
+ * no fade and no count. Chrome's overlay scrollbars are the reason this is not
+ * caught by looking: they appear on scroll, so the first render of a rail that
+ * hides half its content is indistinguishable from a rail that has all of it, and
+ * the last visible row was cut mid-word above dead space, which reads as a
+ * rendering fault rather than as a scroll region.
+ *
+ * **The affordance is a fade across the foot of the scroll region, with the space
+ * it covers reserved rather than borrowed.** Three answers were available and the
+ * other two were rejected for stated reasons. A persistent themed scrollbar is
+ * truthful at both ends and costs nothing to legibility, and it is still here in
+ * the sense that the region is a real scroll region rather than a clipped box,
+ * but it is a single hairline whose length says "there is more" without saying
+ * which way, it needs `scrollbar-gutter` reserved in a 15rem rail to stop the
+ * content shifting when a short tree becomes a tall one, and in Chrome it is the
+ * least reliable of the three to reason about because the property that makes it
+ * persistent is the same one whose default is an overlay. A collapse control needs
+ * a disclosure whose state a server Component cannot hold. An "N more" control is
+ * copy this Page does not ship and it needs the count the Page cannot compute
+ * without measuring, which is the one thing a server Component cannot do.
+ *
+ * So the fade, and it is painted on a wrapper that does not scroll rather than on
+ * the scroll region itself: a mask or a gradient inside the scrollport moves with
+ * the content and marks nothing. The wrapper carries the sticky offset, the
+ * scroll region keeps the cap and the scrolling, and the gradient is pinned to
+ * the wrapper's foot. The region carries `padding-bottom` of the same height, and
+ * that is the half that makes it honest: at rest the gradient falls on reserved
+ * space and the last row is fully legible, and only while there is more below
+ * does it fall on content. Without the padding the same gradient washes the last
+ * row permanently, which is the usual cost of this answer and the reason the
+ * padding is not optional.
+ *
+ * **The fade is paint, and it is on the accessibility tree's terms.** It is an
+ * empty element with `aria-hidden` and `pointer-events-none`, inside the `<nav>`
+ * and outside the `<ul>`, so it is not a list item, it is not announced, it never
+ * takes a press and it never reaches a Tab stop. A keyboard reader scrolls the
+ * region with the arrow keys exactly as before and reaches every entry, and a
+ * screen-reader user is told nothing at all, which is the right answer: the cut is
+ * a fact about ink, and announcing it would put a sentence in the middle of a
+ * list of a consumer's own pages.
+ *
+ * **The tree is in the document once, at every width, and the price of that is a
+ * phone reader crossing the whole navigation to reach the article.** At 768 and
+ * at 1024 both rails used to be `hidden`, so the only navigation left inside
+ * `<main>` was the two-item pager at the foot of the article, and a reader on a
+ * twenty-seven document reference at tablet width had no contents, no
+ * on-this-page and no way to a sibling page except Previous and Next. 0.16.0
+ * closed that gap by drawing the tree a second time behind a `<details>`, one
+ * copy for the rail and one for the narrow frame, and it shipped a doubled
+ * document to every documentation page in the family with it: two
+ * `aria-current` markers for one page, two lists of a consumer's own pages, two
+ * `docs-nav-page` rows for every document, and a second `<nav>` carrying the
+ * rail's own accessible name, which is the thing a consumer's suite reaches the
+ * rail by. Three consumer test files failed against the published package: two on
+ * a count that came back doubled, and two on a `getByRole('navigation', { name })`
+ * that had two answers where it expects one. So there is one copy now, and it
+ * shows at every width.
+ *
+ * **What that costs, with the number.** A consumer's rail measured 1,318 pixels
+ * of content in a built export at 1280 by 680, and those rows wrap on a phone, so
+ * a reader arriving at the top of a documentation page scrolls past a thousand
+ * pixels of navigation before the article begins. That is a real regression for
+ * that reader and it is the reason a disclosure was reached for in the first
+ * place. It is paid rather than hidden, because every arrangement that avoids it
+ * is worse: a rail at `lg` and nothing below it reopens the gap this change
+ * closes, and drawing the tree twice to keep the scroll short is what broke three
+ * consumer test files in the first place.
+ *
+ * **What would actually remove the scroll.** A collapsed rail below `lg` needs an
+ * open state. A server Component cannot hold one, and `<details>` is the only
+ * disclosure the platform holds on the Page's behalf, so the control that opens
+ * it has to be a client island inside the Page. That is a separate piece of work
+ * with its own budget, and it is not built here: a Page that ships a client
+ * boundary to save one scroll is making a different trade than the one stated
+ * above, and it should be made deliberately rather than smuggled in as the side
+ * effect of fixing a duplicate.
  *
  * **The frame is three columns from `lg`, and the third is the consumer's to
  * fill.** The rail is 15rem, the document takes the rest, and the contents rail
  * is 13rem. The third track exists only when `toc` is passed, because the
  * document takes the second track by auto-placement and a template that named a
  * track no child occupies would leave the document in the 15rem one. Below `lg`
- * the frame is a single column with both rails hidden, which is the arrangement
- * a phone gets.
+ * the frame is a single column and the children flow in the order they are
+ * written: the rail, then the document, then the contents rail. The rail is the
+ * first child for that reason, so a reader below `lg` meets the navigation before
+ * the text rather than after it, and one arrangement serves both widths.
  *
  * It is a Page rather than a Block because it is a whole screen and it is the
  * screen a content pipeline targets: a route that reads one document and hands
@@ -284,7 +396,9 @@ export type DocsShellProps = {
  *
  * It is a server Component. It fetches nothing, it holds no state and it imports
  * no router, so a consumer renders it from whichever route their framework names
- * and hands it the document their pipeline produced.
+ * and hands it the document their pipeline produced. Nothing here needs a client
+ * boundary, and the one feature that would want one is named above as work not
+ * done rather than quietly added.
  */
 export declare function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }: DocsShellProps): import("react").JSX.Element;
 export default DocsShell;

package/dist/pages/docs-shell/docs-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-shell.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/docs-shell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAW,EACX,GAAG,EACH,GAAG,EACH,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,cAAc,+BA+FhB;AAwWD,eAAe,SAAS,CAAA"}
+{"version":3,"file":"docs-shell.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/docs-shell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwKG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAW,EACX,GAAG,EACH,GAAG,EACH,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,cAAc,+BAiFhB;AA+fD,eAAe,SAAS,CAAA"}

package/dist/pages/docs-shell/docs-shell.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from '../../components/ui/prose.js';
+import { headingSizeClass } from '../../components/ui/section.js';
 import { Heading, Text } from '../../components/ui/typography.js';
 import { cn } from '../../lib/utils.js';
 /**
@@ -59,21 +60,104 @@ import { cn } from '../../lib/utils.js';
  * author filed it. A Page that sorted its rail would flatten the one thing the
  * three sites disagree about and cannot both be right about.
  *
- * **The rail is bounded in height.** Atlas files nineteen pages and AlphaLens
- * files twenty-seven, so the taller tree is half again as long, and an unbounded
- * rail on a tall tree is a rail that pushes the document below the fold before
- * the reader has read a line of it. The rail and the contents rail are each
- * capped against the viewport and scroll inside it, so a nineteen-page tree and a
- * twenty-seven-page tree are both a full screen and neither is a page-long
- * sidebar.
+ * **The rail is bounded in height, and the bound is what the reader has to be
+ * able to see.** Atlas files nineteen pages and AlphaLens files twenty-seven, so
+ * the taller tree is half again as long, and an unbounded rail on a tall tree is
+ * a rail that pushes the document below the fold before the reader has read a
+ * line of it. The rail and the contents rail are each capped against the viewport
+ * and scroll inside it, so a nineteen-page tree and a twenty-seven-page tree are
+ * both a full screen and neither is a page-long sidebar.
+ *
+ * **A cap the reader cannot see is a defect, and this one was invisible for 344
+ * and 750 pixels.** Measured in two consumers' built exports at 1280 by 680, the
+ * rail's content stood at 912 and 1318 pixels against a 568 pixel box, so more
+ * than half of one site's documentation navigation sat below the fold with
+ * `mask-image: none`, no scrollbar Chrome would draw until the reader scrolled,
+ * no fade and no count. Chrome's overlay scrollbars are the reason this is not
+ * caught by looking: they appear on scroll, so the first render of a rail that
+ * hides half its content is indistinguishable from a rail that has all of it, and
+ * the last visible row was cut mid-word above dead space, which reads as a
+ * rendering fault rather than as a scroll region.
+ *
+ * **The affordance is a fade across the foot of the scroll region, with the space
+ * it covers reserved rather than borrowed.** Three answers were available and the
+ * other two were rejected for stated reasons. A persistent themed scrollbar is
+ * truthful at both ends and costs nothing to legibility, and it is still here in
+ * the sense that the region is a real scroll region rather than a clipped box,
+ * but it is a single hairline whose length says "there is more" without saying
+ * which way, it needs `scrollbar-gutter` reserved in a 15rem rail to stop the
+ * content shifting when a short tree becomes a tall one, and in Chrome it is the
+ * least reliable of the three to reason about because the property that makes it
+ * persistent is the same one whose default is an overlay. A collapse control needs
+ * a disclosure whose state a server Component cannot hold. An "N more" control is
+ * copy this Page does not ship and it needs the count the Page cannot compute
+ * without measuring, which is the one thing a server Component cannot do.
+ *
+ * So the fade, and it is painted on a wrapper that does not scroll rather than on
+ * the scroll region itself: a mask or a gradient inside the scrollport moves with
+ * the content and marks nothing. The wrapper carries the sticky offset, the
+ * scroll region keeps the cap and the scrolling, and the gradient is pinned to
+ * the wrapper's foot. The region carries `padding-bottom` of the same height, and
+ * that is the half that makes it honest: at rest the gradient falls on reserved
+ * space and the last row is fully legible, and only while there is more below
+ * does it fall on content. Without the padding the same gradient washes the last
+ * row permanently, which is the usual cost of this answer and the reason the
+ * padding is not optional.
+ *
+ * **The fade is paint, and it is on the accessibility tree's terms.** It is an
+ * empty element with `aria-hidden` and `pointer-events-none`, inside the `<nav>`
+ * and outside the `<ul>`, so it is not a list item, it is not announced, it never
+ * takes a press and it never reaches a Tab stop. A keyboard reader scrolls the
+ * region with the arrow keys exactly as before and reaches every entry, and a
+ * screen-reader user is told nothing at all, which is the right answer: the cut is
+ * a fact about ink, and announcing it would put a sentence in the middle of a
+ * list of a consumer's own pages.
+ *
+ * **The tree is in the document once, at every width, and the price of that is a
+ * phone reader crossing the whole navigation to reach the article.** At 768 and
+ * at 1024 both rails used to be `hidden`, so the only navigation left inside
+ * `<main>` was the two-item pager at the foot of the article, and a reader on a
+ * twenty-seven document reference at tablet width had no contents, no
+ * on-this-page and no way to a sibling page except Previous and Next. 0.16.0
+ * closed that gap by drawing the tree a second time behind a `<details>`, one
+ * copy for the rail and one for the narrow frame, and it shipped a doubled
+ * document to every documentation page in the family with it: two
+ * `aria-current` markers for one page, two lists of a consumer's own pages, two
+ * `docs-nav-page` rows for every document, and a second `<nav>` carrying the
+ * rail's own accessible name, which is the thing a consumer's suite reaches the
+ * rail by. Three consumer test files failed against the published package: two on
+ * a count that came back doubled, and two on a `getByRole('navigation', { name })`
+ * that had two answers where it expects one. So there is one copy now, and it
+ * shows at every width.
+ *
+ * **What that costs, with the number.** A consumer's rail measured 1,318 pixels
+ * of content in a built export at 1280 by 680, and those rows wrap on a phone, so
+ * a reader arriving at the top of a documentation page scrolls past a thousand
+ * pixels of navigation before the article begins. That is a real regression for
+ * that reader and it is the reason a disclosure was reached for in the first
+ * place. It is paid rather than hidden, because every arrangement that avoids it
+ * is worse: a rail at `lg` and nothing below it reopens the gap this change
+ * closes, and drawing the tree twice to keep the scroll short is what broke three
+ * consumer test files in the first place.
+ *
+ * **What would actually remove the scroll.** A collapsed rail below `lg` needs an
+ * open state. A server Component cannot hold one, and `<details>` is the only
+ * disclosure the platform holds on the Page's behalf, so the control that opens
+ * it has to be a client island inside the Page. That is a separate piece of work
+ * with its own budget, and it is not built here: a Page that ships a client
+ * boundary to save one scroll is making a different trade than the one stated
+ * above, and it should be made deliberately rather than smuggled in as the side
+ * effect of fixing a duplicate.
  *
  * **The frame is three columns from `lg`, and the third is the consumer's to
  * fill.** The rail is 15rem, the document takes the rest, and the contents rail
  * is 13rem. The third track exists only when `toc` is passed, because the
  * document takes the second track by auto-placement and a template that named a
  * track no child occupies would leave the document in the 15rem one. Below `lg`
- * the frame is a single column with both rails hidden, which is the arrangement
- * a phone gets.
+ * the frame is a single column and the children flow in the order they are
+ * written: the rail, then the document, then the contents rail. The rail is the
+ * first child for that reason, so a reader below `lg` meets the navigation before
+ * the text rather than after it, and one arrangement serves both widths.
  *
  * It is a Page rather than a Block because it is a whole screen and it is the
  * screen a content pipeline targets: a route that reads one document and hands
@@ -84,7 +168,9 @@ import { cn } from '../../lib/utils.js';
  *
  * It is a server Component. It fetches nothing, it holds no state and it imports
  * no router, so a consumer renders it from whichever route their framework names
- * and hands it the document their pipeline produced.
+ * and hands it the document their pipeline produced. Nothing here needs a client
+ * boundary, and the one feature that would want one is named above as work not
+ * done rather than quietly added.
  */
 export function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }) {
     readTree(nav, 'nav');
@@ -92,6 +178,8 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
     const rail = nav && nav.length > 0 ? nav : undefined;
     const contents = toc && toc.length > 0 ? toc : undefined;
     const neighbours = currentHref === undefined ? undefined : deriveNeighbours(nav ?? [], currentHref);
+    const unnamedNav = unnamedIn(nav);
+    const unnamedToc = unnamedIn(toc);
     return (_jsxs("div", { "data-slot": "docs-shell", className: cn('mx-auto w-full max-w-page px-6 py-10 lg:px-8', className), children: [header, _jsxs("div", { "data-slot": "docs-shell-frame", className: cn('flex flex-col gap-8 lg:flex-row lg:gap-10', 
                 // One track for the rail, one for the document, and a third for the
                 // contents rail when there is one. The template names exactly the
@@ -107,7 +195,73 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
                 // contents rail landed in an implicit `auto` track rather than the
                 // 13rem one. `check-breakpoint-variants.mjs` is the gate that says so
                 // to the next class written against a screen the theme does not emit.
-                contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "hidden lg:col-start-1 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": navLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4", children: _jsx(NavList, { entries: rail, currentHref: currentHref, depth: 0 }) }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", size: "3xl", children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "hidden lg:col-start-3 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": tocLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto", children: _jsx(NavList, { entries: contents, currentHref: currentHref, depth: 0 }) }) })) : null] }), footer] }));
+                contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "lg:col-start-1 lg:row-start-1", children: _jsx(Rail, { label: navLabel, entries: rail, currentHref: currentHref, unnamed: unnamedNav }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", className: headingSizeClass('h1'), children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "lg:col-start-3 lg:row-start-1", children: _jsx(Rail, { label: tocLabel, entries: contents, currentHref: currentHref, unnamed: unnamedToc }) })) : null] }), footer] }));
+}
+/* ------------------------------------------------------------------ *
+ * The two rails
+ * ------------------------------------------------------------------ */
+/**
+ * One rail: a region that scrolls inside a bound against the viewport, with the
+ * cut at its foot marked so the rows below it are discoverable.
+ *
+ * **The sticky offset is on this wrapper and not on the scroll region, and the
+ * reason is the fade.** The fade has to be pinned to the foot of the region while
+ * the region scrolls, and nothing inside a scroll container stays put while that
+ * container scrolls: a gradient or a mask written into the scrollport travels with
+ * the content and so marks nothing once the reader has scrolled. The wrapper is
+ * the element that travels, so the fade is absolutely positioned against it and
+ * the `<nav>` inside is free to be nothing but the scroll region.
+ *
+ * The cap is `100svh` less the sticky offset plus the gap under it, and `svh` is
+ * the smallest viewport height rather than the largest, which is the direction that
+ * matters here. `dvh` would grow to the full height the moment a mobile browser's
+ * URL bar retracted, and a sticky region measured against a viewport taller than
+ * the one on screen is a region whose foot is below the bottom of the screen
+ * while it is pinned, which is the one state the bound exists to prevent. `svh`
+ * is never taller than what is visible, so `top` plus `max-h` is always inside the
+ * viewport and the rail's foot always clears it. `top-20` is 5rem and the cap is
+ * the viewport less 7rem, so the foot sits 2rem above the bottom edge at every
+ * window height; a short window makes the rail shorter and does not make it
+ * taller than the space it is pinned in.
+ *
+ * `padding-bottom` is the same height as the fade, and it is what makes the fade
+ * honest. The gradient falls on the last 2rem of whatever the scrollport is
+ * showing, so with the padding reserved it falls on empty space once the reader
+ * has reached the end and on content only while there is more below. Without it
+ * the same gradient permanently washes the bottom of the last row, which is the
+ * usual cost of a fade and the reason the padding is part of the answer rather
+ * than a detail.
+ *
+ * **The bound, the sticky offset, the band and the fade are all written against
+ * the same `lg:`, so below `lg` this rail is an ordinary block in the flow: no
+ * scroll region, no cut, no reservation, no fade.** That is the right shape for a
+ * rail that is the first thing in a single column, because a sticky region a full
+ * viewport tall above the article would be worse than a long one above it.
+ *
+ * **The fade and the band are bound to the cut rather than to the rail, and the
+ * reason is what a fade is for.** A fade marks a cut, so it may only exist where
+ * there is one, and the cut is the `overflow-y` at `lg`: the scroll region, the
+ * cap, the sticky offset, the reserved band and the gradient are one arrangement
+ * or none of them. The fade shipped unprefixed, which put the arrangement out of
+ * step with itself at the one width that has no cut to mark. Below `lg` the region
+ * is an ordinary block, so the `pb-8` reserving the band is inert there and the
+ * gradient fell on the last row or two of a rail that was simply running on. The
+ * band and the fade still measured equal and the reader still lost nothing
+ * legible, which is why looking did not catch it: a gradient painted over content
+ * is a defect, and it is not a legibility one.
+ *
+ * **The limit bought here is stated rather than left to be found.** Below `lg` the
+ * rail is bounded by its content rather than by the viewport, so a long tree runs
+ * past the fold of a phone screen with nothing marking where it ends: no cut to
+ * mark, no band to reserve and no scroll region to scroll inside. That is the
+ * honest price of one copy of the tree at every width, and the measurement behind
+ * it is stated once on the Page above rather than repeated here.
+ *
+ * `unnamed` is carried on the `<nav>` rather than logged, for the reason
+ * `unnamedIn` gives.
+ */
+function Rail({ label, entries, currentHref, unnamed, }) {
+    return (_jsxs("div", { className: "relative lg:sticky lg:top-20", children: [_jsx("nav", { "aria-label": label, "data-unnamed-entries": unnamed, className: "lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4 lg:pb-8", children: _jsx(NavList, { entries: entries, currentHref: currentHref, depth: 0 }) }), _jsx("div", { "aria-hidden": "true", "data-slot": "docs-rail-fade", className: "pointer-events-none lg:absolute lg:inset-x-0 lg:bottom-0 lg:h-8 lg:bg-gradient-to-t lg:from-background lg:to-transparent" })] }));
 }
 /* ------------------------------------------------------------------ *
  * The tree
@@ -124,6 +278,21 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
 function addressOf(href) {
     return href !== undefined && href.trim() !== '' ? href : undefined;
 }
+/**
+ * Whether an entry has words to be called by.
+ *
+ * Blank counts as none, for the same reason `addressOf` counts it: all three
+ * consumer adapters build a title out of whatever their content pipeline produced,
+ * and one of them maps a heading whose title arrives as a React element to the
+ * empty string. A row is rendered from a string, and a string of spaces is not a
+ * name. It is read here rather than at each use because `destinationOf` decides
+ * between a link and a label, the renderer decides between a row and nothing, and
+ * the counter decides how many rows went missing, and three answers to one
+ * question is how a fourth grows.
+ */
+function named(entry) {
+    return entry.title.trim() !== '';
+}
 /**
  * The address an entry is reachable at, or `undefined` when it is not a
  * destination at all.
@@ -136,7 +305,35 @@ function addressOf(href) {
  * `Next` link under it.
  */
 function destinationOf(entry) {
-    return entry.title === '' ? undefined : addressOf(entry.href);
+    return named(entry) ? addressOf(entry.href) : undefined;
+}
+/**
+ * How many entries in a tree the Page cannot name, and therefore did not draw.
+ *
+ * **It is counted rather than swallowed, and the place it is counted on is the
+ * rail itself.** `Diagram` answers a dropped relation the same way, with
+ * `data-unresolved-relations` on the drawing, and the argument is the same one: a
+ * row that did not draw is a fact about the caller's data, and a fact that leaves
+ * no trace is a defect the next reader has to rediscover from a screenshot. The
+ * number is on the element rather than in a console because a caller reads the
+ * element and does not read the console.
+ *
+ * Three things are counted, because three things go missing rather than two:
+ * a page with no words, which is dropped whole; a group with no words, whose
+ * label is not rendered while its pages still are; and a group with neither words
+ * nor children, which has nothing left to draw and is dropped whole.
+ */
+function unnamedIn(entries) {
+    let count = 0;
+    for (const entry of entries ?? []) {
+        if (entry.type === 'divider')
+            continue;
+        if (!named(entry))
+            count += 1;
+        if (entry.type === 'group')
+            count += unnamedIn(entry.items);
+    }
+    return count;
 }
 /**
  * Reads a tree before any of it renders, and refuses the one shape it cannot
@@ -205,15 +402,23 @@ function NavNode({ entry, currentHref, depth, }) {
     }
     const href = destinationOf(entry);
     if (entry.type === 'group') {
-        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+        // A group with no words and no pages has nothing left to draw, and a `<li>`
+        // holding an empty `<div>` is the same empty row the page arm used to render.
+        // Dropping it costs nothing, because there was nothing in it.
+        if (!named(entry) && entry.items.length === 0)
+            return null;
+        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [!named(entry) ? null : href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
     }
-    // The page arm. `href` is never empty here: `readTree` refused that above and
-    // named the entry, so what is left to decide is the words. A nameless page is
-    // the same rule as a group with no index, rendered as a label, because a link
-    // with no accessible name is announced as "link" and nothing else.
-    return (_jsx("li", { "data-slot": "docs-nav-page", children: href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: "-ms-px block border-l-2 border-transparent py-1 ps-3 text-sm text-muted-foreground", children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-link", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === href
+    // The page arm, and there is one shape of it left. `readTree` refused a page
+    // with no address above and named the entry, so every page that reaches here has
+    // one, and a page with no words is not rendered at all rather than rendered as
+    // a label: a link with no accessible name is announced as "link" and nothing
+    // else, and a blank row is not a label either because a label is words.
+    if (!named(entry))
+        return null;
+    return (_jsx("li", { "data-slot": "docs-nav-page", children: _jsx("a", { "data-slot": "docs-nav-link", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === href
                 ? 'text-foreground border-primary font-medium'
-                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title })) }));
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title }) }));
 }
 /**
  * Every page the tree holds, in the order a reader meets them.
@@ -225,11 +430,12 @@ function NavNode({ entry, currentHref, depth, }) {
  * the pager to reach either. A divider contributes nothing at all.
  *
  * The row a reader can click and the row the pager can reach are decided by the
- * SAME function, `destinationOf`. A nameless entry is a label on the rail and is
- * dropped here, so one malformed row cannot be published twice: a nameless anchor
- * in the rail, and a `Next` link under it carrying the text of whichever entry
- * happened to follow, is what deriving without asking produced. The two surfaces
- * do not each get their own opinion about a row that is not a page.
+ * SAME function, `destinationOf`, and a row with no words is now dropped from the
+ * rail as well, so the two surfaces agree twice over rather than once by accident.
+ * The defect this replaced was a nameless anchor in the rail and a `Next` link
+ * under it carrying the text of whichever entry happened to follow, published
+ * from one malformed row. Deriving without asking produced the first and a
+ * separate opinion produced the second; asking once produces neither.
  */
 function flatten(entries, into = []) {
     for (const entry of entries) {

package/dist/pages/error-page/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/error-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIpF;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAC1C,CACI;IACE;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB,GACD;IACE,mCAAmC;IACnC,SAAS,CAAC,EAAE,KAAK,CAAA;IACjB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,KAAK,CAAA;CACvB,CACJ,CAAA;AAqBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAmB,EACnB,SAAS,GACV,EAAE,cAAc,+BAkEhB;AAED,eAAe,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/error-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAItG;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAC1C,CACI;IACE;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB,GACD;IACE,mCAAmC;IACnC,SAAS,CAAC,EAAE,KAAK,CAAA;IACjB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,KAAK,CAAA;CACvB,CACJ,CAAA;AAqBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAmB,EACnB,SAAS,GACV,EAAE,cAAc,+BAqEhB;AAED,eAAe,SAAS,CAAA"}

package/dist/pages/error-page/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CtaLink } from '../../components/ui/cta-link.js';
 import { Prose } from '../../components/ui/prose.js';
-import { Section, childLevel } from '../../components/ui/section.js';
+import { Section, childLevel, headingSizeClass } from '../../components/ui/section.js';
 import { Heading, Text } from '../../components/ui/typography.js';
 import { cn } from '../../lib/utils.js';
 /**
@@ -90,9 +90,13 @@ export function ErrorPage({ code, title, description, retry, links, linksLabel,
     assertReference(reference, referenceLabel);
     /*
       The headline sits one step below the code, which is the same derivation every
-      Block uses and the reason a hardcoded `h2` would be right exactly once.
+      Block uses and the reason a hardcoded `h2` would be right exactly once. The
+      size is asked of the same table rather than passed to `Heading`'s `size`, which
+      is a step of the scale and not a rung of the ladder, so the code and the
+      headline were drawn at fixed sizes that the ladder's ceiling has since left
+      behind.
     */
     const TitleHeading = childLevel(headingLevel);
-    return (_jsx(Section, { "data-slot": "error-page", className: cn(className), children: _jsxs("div", { "data-slot": "error-page-body", className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: headingLevel, size: "4xl", className: "text-muted-foreground font-mono", children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: TitleHeading, size: "2xl", children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), retry === undefined ? null : (_jsx("div", { "data-slot": "error-page-retry", children: retry })), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, reference === undefined ? null : (_jsxs("dl", { "data-slot": "error-page-reference", className: "flex flex-col items-start gap-1", children: [_jsx("dt", { className: "text-muted-foreground text-xs", children: referenceLabel }), _jsx("dd", { className: "font-mono text-sm", children: reference })] })), children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
+    return (_jsx(Section, { "data-slot": "error-page", className: cn(className), children: _jsxs("div", { "data-slot": "error-page-body", className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: headingLevel, className: cn('text-muted-foreground font-mono', headingSizeClass(headingLevel)), children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: TitleHeading, className: headingSizeClass(TitleHeading), children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), retry === undefined ? null : (_jsx("div", { "data-slot": "error-page-retry", children: retry })), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, reference === undefined ? null : (_jsxs("dl", { "data-slot": "error-page-reference", className: "flex flex-col items-start gap-1", children: [_jsx("dt", { className: "text-muted-foreground text-xs", children: referenceLabel }), _jsx("dd", { className: "font-mono text-sm", children: reference })] })), children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
 }
 export default ErrorPage;

package/dist/pages/not-found-page/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/not-found-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,UAAU,EACV,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BA+BnB;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/not-found-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAQtC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,UAAU,EACV,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BA+BnB;AAED,eAAe,YAAY,CAAA"}

package/dist/pages/not-found-page/index.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CtaLink } from '../../components/ui/cta-link.js';
-import { Heading, Text } from '../../components/ui/typography.js';
 import { Prose } from '../../components/ui/prose.js';
-import { Section } from '../../components/ui/section.js';
+import { Section, headingSizeClass } from '../../components/ui/section.js';
+import { Heading, Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
 /**
  * A complete not-found screen: the code, what happened, and the ways out.
  *
@@ -41,6 +42,6 @@ import { Section } from '../../components/ui/section.js';
  * route their framework names.
  */
 export function NotFoundPage({ code, title, description, links, linksLabel, children, className, }) {
-    return (_jsx(Section, { className: className, children: _jsxs("div", { className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: "h1", size: "4xl", className: "text-muted-foreground font-mono", children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h2", size: "2xl", children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
+    return (_jsx(Section, { className: className, children: _jsxs("div", { className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: "h1", className: cn('text-muted-foreground font-mono', headingSizeClass('h1')), children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h2", className: headingSizeClass('h2'), children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
 }
 export default NotFoundPage;