tosijs-ui 1.16.38 → 1.16.39

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.16.39
+
+- **The doc-site frame passes WCAG 2.2 AA where an axe scan said it did not (#3520).** An
+  adopter's scan found four failures in the frame, so every doc site had them:
+  - The header's "Search documentation" trigger and its ⌘K hint measured 1.88:1 (AA asks
+    4.5:1). `--placeholder-color` was the brand at 40% opacity; it is now the brand darkened
+    (or, in dark mode, brightened) just far enough to reach 4.5:1 on the input, for any accent.
+    It colours every `::placeholder` on a doc site, live-example inputs included, so
+    placeholders are darker everywhere.
+  - Code (inline and in blocks) was the brand colour, 4.56:1 on the page and 3.72:1 inside a
+    blockquote. It is now `--code-color`: the brand made readable on the blockquote and code
+    backgrounds. It is computed from your config's `accent`, so code no longer follows a
+    runtime override of `--brand-color`; set `--code-color` too if you do that.
+  - Each nav section was `<details><summary><a>`, a link inside a control, which a screen reader
+    announces as one and loses the other. A section is now a toggle `<button>` beside its link,
+    with `aria-expanded` and `aria-controls`, at least 24px square (the old triangle was under
+    WCAG 2.2's target size). Without JavaScript every section is open, since nothing could open
+    one. Until the bundle loads, a small script in each generated page opens and closes
+    sections, so a slow or failed bundle does not strand a reader; it also marks `<html>` with
+    `tosi-js`. A doc browser made with `createDocBrowser` outside `<tosi-doc-system>` brings
+    its own section styles. **If your site's CSS targets `.doc-nav details` or
+    `.doc-nav summary`, it no longer matches**: use `.doc-nav .nav-branch` (`.-open` when
+    open), `.nav-branch-head` and `.nav-toggle`.
+  - A code block that scrolls sideways could not be reached by keyboard. Static code blocks are
+    now focusable once the page hydrates.
+- **`devServer()` builds on start when it is watching (#3524).** The documented `bin/site.ts`
+  one-liner never built: it served whatever the previous run left in the output folder, so a
+  config change (a theme accent, an ePub cover) showed nothing until a source file changed, and
+  nothing said the page was stale. (`DEV_NO_WATCH=1` and `{ test: true }` still serve what is
+  there.) **If your script builds and then calls `devServer`, as the full-pipeline example in
+  the docs used to, it now builds twice on start**: pass `initialBuild: false`, or drop your
+  own build. That build is your `build` function when you pass one, so the dependency audit
+  inside `buildSite` runs there too, and a blocking advisory leaves the server up with the
+  failure on the page rather than exiting. The config file itself is not watched: restart the
+  server after editing it.
+- **A table has a margin (#3553).** Tables were the one block element without one, so a
+  blockquote after one sat flush against it. The ePub was already right.
+
 ## 1.16.38
 
 - **The ePub carries its images (#3519).** Every local image went into the book as a site path

package/dist/doc-browser.d.ts

@@ -132,4 +132,5 @@ export interface DocBrowserOptions {
      */
     contentElement?: HTMLElement;
 }
+export declare function focusableCodeBlocks(root: ParentNode): void;
 export declare function createDocBrowser(options: DocBrowserOptions): HTMLElement;

package/dist/doc-browser.js

@@ -102,6 +102,7 @@ or embeds more than one browser, passes `searchShortcut: ''` (or another key in
 import { elements, vars, varDefault, bindings, getListItem, tosi, StyleSheet, } from 'tosijs';
 import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, wikilinkTargets, } from './doc-system/routing.js';
 import { buildNavTree } from './doc-system/nav-tree.js';
+import { navSectionStyleSpec } from './doc-system/nav-styles.js';
 import { renderDocMarkdown } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
 import { unsettledExamples, tallyExamples, closePage, } from './doc-system/test-completion.js';
@@ -148,7 +149,7 @@ export const hasTestBlock = (text, policy = 'auto') => typeof text === 'string'
     // Cheap reject first: lexing every doc in a large corpus is not free.
     text.includes('test') &&
     collectCodeTokens(text).some((t) => t.lang === 'test' && isLiveFence('test', t.mode, policy));
-const { div, span, a, header, button, template, h2, img, details, summary, ul, li, } = elements;
+const { div, span, a, header, button, template, h2, img, ul, li } = elements;
 /*
 Test colors, and the text color that goes ON each — because contrast is a PAIR.
 
@@ -374,9 +375,25 @@ const logoMarkStyleSpec = {
     // Inline-<svg> logos are wrapped in a flex holder; scale the embedded svg to it.
     '.logo-mark > svg': { height: '100%', width: 'auto' },
 };
+/*
+A code block that scrolls sideways must be reachable by keyboard, or its overflow cannot be
+read without a pointer (WCAG 2.1.1, axe `scrollable-region-focusable`, #3520). Every static
+block gets it, not only the ones overflowing now: overflow changes with the window, and a
+check at render time would go stale on the first resize. Done here rather than in the
+markdown renderer so the pre-rendered page stays byte-identical to what it was.
+*/
+export function focusableCodeBlocks(root) {
+    for (const pre of root.querySelectorAll('pre')) {
+        if (pre.hasAttribute('tabindex') || pre.closest('tosi-example'))
+            continue;
+        pre.tabIndex = 0;
+    }
+}
 // Monotonic per-page counter so each createDocBrowser() call gets a distinct
 // tosi() registry key (see stateKey below) and two browsers can't share state.
 let docBrowserSeq = 0;
+// Likewise for the nav's aria-controls ids.
+let navIdCounter = 0;
 export function createDocBrowser(options) {
     const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
@@ -1094,6 +1111,7 @@ export function createDocBrowser(options) {
         // Stamp each example with its source file (for the source↔doc map). doc.path
         // is the extracted file (.md, or a source file with doc comments).
         LiveExample.insertExamples(docContent, context, doc.path || undefined);
+        focusableCodeBlocks(docContent);
         /*
         Highlight whatever is left — the static blocks that are not live examples.
     
@@ -1327,6 +1345,7 @@ export function createDocBrowser(options) {
             docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks });
             rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
+            focusableCodeBlocks(docContent);
         }
         else if (view === 'diff') {
             docContent.replaceChildren(tosiDiff({
@@ -1506,7 +1525,7 @@ export function createDocBrowser(options) {
         return menuItems;
     };
     // ── Hierarchical nav (path routing) ───────────────────────────────────────
-    // Build nested <details> from the doc tree; current-highlight, test status,
+    // Build nested sections from the doc tree; current-highlight, test status,
     // search visibility, and auto-open are applied imperatively by refreshNav.
     const navStyle = {
         slot: 'nav',
@@ -1523,6 +1542,8 @@ export function createDocBrowser(options) {
     };
     const buildHierarchicalNav = () => {
         const roots = buildNavTree(docs, slugMap);
+        // Ids for aria-controls, unique per browser: an embedded doc browser shares the page.
+        const navIdPrefix = `tosi-nav-${(navIdCounter += 1)}-`;
         const leaves = new Map();
         const branches = [];
         const subtreeFilenames = (node) => {
@@ -1560,18 +1581,39 @@ export function createDocBrowser(options) {
                 leaves.set(node.doc.filename, { li: item, link });
                 return item;
             }
-            const det = details(summary(link), ul(...node.children.map(renderNode)));
-            const item = li(det);
+            /*
+            A toggle button BESIDE the link, not a <summary> around it (#3520): a link inside a
+            summary is a control inside a control. Same markup as the static nav
+            (`navToggleHtml` in generate-site.ts), so hydration does not move anything.
+            */
+            const listId = `${navIdPrefix}${node.slug || 'home'}`;
+            const toggle = button({
+                type: 'button',
+                class: 'nav-toggle',
+                ariaExpanded: 'false',
+                ariaControls: listId,
+                ariaLabel: String(node.doc.title),
+                onClick: () => section.setOpen(!item.classList.contains('-open')),
+            });
+            const item = li({ class: 'nav-branch' }, div({ class: 'nav-branch-head' }, toggle, link), ul({ id: listId }, ...node.children.map(renderNode)));
+            const section = {
+                setOpen(open) {
+                    item.classList.toggle('-open', open);
+                    toggle.setAttribute('aria-expanded', String(open));
+                },
+            };
             branches.push({
                 li: item,
-                el: det,
+                el: section,
                 link,
                 filename: node.doc.filename,
                 subtree: subtreeFilenames(node),
             });
             return item;
         };
-        const root = div(navStyle, ul(...roots.map(renderNode)));
+        // `-live`: these sections have working toggles, so closed ones collapse even where no
+        // pre-paint script marked <html> (a browser embedded outside a generated page).
+        const root = div({ ...navStyle, class: `${navStyle.class} -live` }, ul(...roots.map(renderNode)));
         const applyStatus = (link, filename, current) => {
             link.classList.toggle('current', filename === current);
             const r = pageTestResults[filename];
@@ -1590,9 +1632,9 @@ export function createDocBrowser(options) {
                 // On navigation (resetOpen), collapse everything except the current doc's section.
                 // Otherwise (e.g. test-status refresh) leave user toggles alone.
                 if (resetOpen)
-                    el.open = subtree.includes(current);
+                    el.setOpen(subtree.includes(current));
                 else if (subtree.includes(current))
-                    el.open = true;
+                    el.setOpen(true);
             }
         };
         refreshNav(true);
@@ -1691,6 +1733,7 @@ export function createDocBrowser(options) {
     // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
     StyleSheet('doc-logo-mark', logoMarkStyleSpec);
     StyleSheet('doc-nav-search', navSearchStyleSpec);
+    StyleSheet('doc-nav-sections', navSectionStyleSpec);
     /*
     The far end has something to tell you.
   

package/dist/doc-system/doc-system-styles.d.ts

@@ -1,4 +1,4 @@
-import { XinStyleSheet, XinStyleRule } from 'tosijs';
+import { XinStyleSheet, XinStyleRule, Color } from 'tosijs';
 export declare const SIDEBAR_WIDTH = 200;
 export declare const SIDEBAR_BREAKPOINT = 600;
 export interface DocSystemTheme {
@@ -22,6 +22,17 @@ export interface DocSystemTheme {
      */
     codeBg?: string;
 }
+/**
+ * WCAG 2 contrast ratio between two opaque colors. Throws on a translucent one: its real
+ * contrast depends on what is behind it, and ignoring alpha measured the old 40%-opacity
+ * placeholder at 4.74:1 where axe, compositing it, measured 1.88:1.
+ */
+export declare function contrastRatio(a: Color, b: Color): number;
+/**
+ * `color`, darkened (on a light `bg`) or brightened (on a dark one) just far enough to reach
+ * `min` contrast against `bg`, so it keeps as much of its hue as AA allows.
+ */
+export declare function readableOn(color: Color, bg: Color, min?: number): Color;
 /** Compute the full set of `:root` color variables from a few base colors. */
 export declare function docSystemColors(theme?: DocSystemTheme): XinStyleRule;
 /** Build the full doc-system stylesheet for a given base theme. */

package/dist/doc-system/doc-system-styles.js

@@ -10,6 +10,7 @@ Colors are computed from a small set of base colors via tosijs `Color` math, so
 palette can eventually be driven entirely by a few attributes on the element
 (accent/background/text) — most of the palette is derived from `accent`.
 */
+import { navSectionStyleSpec } from './nav-styles.js';
 import { highlightStyleSpec } from './highlight-styles.js';
 import { vars, Color, invertLuminance, } from 'tosijs';
 import { icons, svg2DataUrl } from '../icons.js';
@@ -19,6 +20,36 @@ import { icons, svg2DataUrl } from '../icons.js';
 // `SIDEBAR_BREAKPOINT`. Keep them in step, or the page jumps as it hydrates.
 export const SIDEBAR_WIDTH = 200;
 export const SIDEBAR_BREAKPOINT = 600;
+/**
+ * WCAG 2 contrast ratio between two opaque colors. Throws on a translucent one: its real
+ * contrast depends on what is behind it, and ignoring alpha measured the old 40%-opacity
+ * placeholder at 4.74:1 where axe, compositing it, measured 1.88:1.
+ */
+export function contrastRatio(a, b) {
+    if (a.RGBA[3] < 1 || b.RGBA[3] < 1)
+        throw new Error('contrastRatio: composite a translucent color first');
+    const lum = (c) => {
+        const [r, g, bl] = c.RGBA.map((v) => v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+        return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
+    };
+    const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * `color`, darkened (on a light `bg`) or brightened (on a dark one) just far enough to reach
+ * `min` contrast against `bg`, so it keeps as much of its hue as AA allows.
+ */
+export function readableOn(color, bg, min = 4.5) {
+    const darkBg = contrastRatio(bg, Color.black) < contrastRatio(bg, Color.white);
+    // Measured on the hex the stylesheet will actually carry: rounding to 8-bit channels
+    // can drop a ratio just over `min` to just under it.
+    const shipped = (c) => Color.fromCss(c.html);
+    let c = shipped(color.opaque);
+    for (let step = 0; step < 20 && contrastRatio(c, bg) < min; step++) {
+        c = shipped(darkBg ? c.brighten(0.1) : c.darken(0.1));
+    }
+    return contrastRatio(c, bg) < min ? bg.contrasting() : c;
+}
 /** Compute the full set of `:root` color variables from a few base colors. */
 export function docSystemColors(theme = {}) {
     const brandColor = Color.fromCss(theme.accent ?? '#d92270');
@@ -32,7 +63,12 @@ export function docSystemColors(theme = {}) {
         _navBg: brandColor.rotate(30).desaturate(0.5).brighten(0.9),
         _barColor: brandColor.opacity(0.4),
         _focusColor: brandColor.opacity(0.7),
-        _placeholderColor: brandColor.opacity(0.4),
+        /*
+        Readable, not faint (#3520). This was the brand at 40% opacity, which an axe scan measured
+        at 1.88:1 on the input (#eda7c5 on #fdfdfd) where AA asks 4.5:1, and it colours the doc
+        header's "Search documentation" trigger, a real label, not just a hint.
+        */
+        _placeholderColor: readableOn(brandColor, Color.fromCss(theme.inputBg ?? '#fdfdfd')),
         /*
         `contrasting()` rather than a hand-tuned tint.
     
@@ -46,6 +82,10 @@ export function docSystemColors(theme = {}) {
         */
         _brandTextColor: brandColor.contrasting(),
         _insetBg: brandColor.rotate(45).brighten(0.8),
+        // The brand, made readable on the inset (blockquote) background, the darker of the two
+        // surfaces code sits on. The raw brand measured 3.72:1 there (#3520).
+        // Checked against the code background too: a custom `codeBg` can be the darker one.
+        _codeColor: readableOn(readableOn(brandColor, brandColor.rotate(45).brighten(0.8)), Color.fromCss(theme.codeBg ?? '#fdfdfd')),
         // Neutral off-white (not brand-tinted); dark mode inverts its luminance to
         // off-black, so the editor surface stays a clean neutral in both themes.
         _codeBg: theme.codeBg ?? '#fdfdfd',
@@ -182,6 +222,8 @@ export function docSystemStyleSpec(theme = {}) {
             brand, the luminance belongs to the background it sits on.
             */
             _brandColor: brandColor.brighten(0.18),
+            _codeColor: readableOn(readableOn(brandColor.brighten(0.18), brandColor.rotate(45).brighten(0.8).inverseLuminance), Color.fromCss(theme.codeBg ?? '#fdfdfd').inverseLuminance),
+            _placeholderColor: readableOn(brandColor.brighten(0.18), Color.fromCss(theme.inputBg ?? '#fdfdfd').inverseLuminance),
             _shadowColor: brandColor.opacity(0.5),
             _menuShadow: `0 0 0 2px ${brandColor.opacity(0.75)}`,
             _menuSeparatorColor: brandColor.opacity(0.5),
@@ -281,9 +323,9 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'none',
         },
         // Wide enough for the sidebar: reserve its column, and show the REAL nav tree
-        // in it. It's a plain <ul> with native <details> groups, so it navigates and
-        // collapses without a line of JavaScript — a no-JS reader gets a working site,
-        // and hydration merely upgrades it in place.
+        // in it. It's a plain <ul> of real links, every section expanded when there is no
+        // JavaScript to collapse one (no `tosi-js` on <html>) — a no-JS reader gets a
+        // working site, and hydration merely upgrades it in place.
         [`@media (min-width: ${SIDEBAR_BREAKPOINT}px)`]: {
             'tosi-doc-system:not(:defined)': {
                 left: `${SIDEBAR_WIDTH}px`,
@@ -314,9 +356,6 @@ export function docSystemStyleSpec(theme = {}) {
             //
             // Only genuinely pre-hydration-specific rules belong in this block — the fixed
             // positioning above, which the upgraded component takes over itself.
-            'tosi-doc-system:not(:defined) .doc-nav summary': {
-                cursor: 'pointer',
-            },
         },
         '.center': {
             display: 'flex',
@@ -507,7 +546,7 @@ export function docSystemStyleSpec(theme = {}) {
             // `--text-color` token rather than setting a colour, so everything inside a `<pre>`
             // — including every syntax-highlighting token span — inherited a palette where the
             // theme's text colour had been replaced by the brand colour.
-            color: vars.brandColor,
+            color: vars.codeColor,
         },
         /*
         Prism token colours for STATIC code blocks — TWO palettes, because there are two
@@ -554,7 +593,7 @@ export function docSystemStyleSpec(theme = {}) {
             boxShadow: 'none',
             color: vars.textColor,
         },
-        '.current, summary:has(.current)': {
+        '.current, .nav-branch-head:has(.current)': {
             background: vars.background,
         },
         '.doc-link': {
@@ -584,8 +623,11 @@ export function docSystemStyleSpec(theme = {}) {
         "[class*='icon-']": {
             verticalAlign: 'middle',
         },
+        // Every other block element brings its own margin; without one a table sat flush
+        // against a following blockquote, whose top margin is 0 by design (#3553).
         table: {
             borderCollapse: 'collapse',
+            margin: `${vars.spacing} 0 ${vars.spacing200} 0`,
         },
         thead: {
             background: vars.brandColor,
@@ -601,7 +643,7 @@ export function docSystemStyleSpec(theme = {}) {
             padding: 'calc(var(--spacing) * 0.5) var(--spacing)',
         },
         // Nav lists carry semantics only — no list styling. Hierarchy indentation
-        // comes from left-padding on each section's child list (inside <details>).
+        // comes from left-padding on each section's child list.
         '.doc-nav ul, .doc-nav li': {
             listStyle: 'none',
             margin: 0,
@@ -615,44 +657,7 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'flex',
             flexDirection: 'column',
         },
-        '.doc-nav details > ul': {
-            paddingLeft: vars.spacing,
-        },
-        // Collapse a closed section's list SYNCHRONOUSLY. The UA collapses <details>
-        // via `::details-content { content-visibility: hidden }`, which is applied
-        // lazily and — for this static tree — non-deterministically on first paint:
-        // sometimes the closed section is still laid out at full height for a frame
-        // before it snaps shut. That frame is a visible flicker on refresh, and it made
-        // the "nav does not move on hydration" test measure a 36px row that hydration
-        // then collapses to 0. An explicit display:none collapses it in the first layout
-        // pass with no content-visibility race, and still opens on a no-JS <summary>
-        // toggle (the UA adds [open], so this rule stops matching).
-        '.doc-nav details:not([open]) > ul': {
-            display: 'none',
-        },
-        // <summary> is the section header (its triangle toggles; the link navigates).
-        '.doc-nav summary': {
-            cursor: 'pointer',
-            // indent the disclosure marker a bit from the edge
-            paddingLeft: 'calc(var(--spacing) * 0.5)',
-        },
-        '.doc-nav summary::marker': {
-            color: vars.brandColor,
-        },
-        '.doc-nav summary > .doc-link': {
-            display: 'inline-block',
-            // push the summary text in a bit less than a normal doc-link
-            paddingLeft: 'calc(var(--spacing) * 0.5)',
-            /*
-            Room for the disclosure triangle on the same line (#219). An inline-block as wide as
-            its text does not fit beside the marker once the title is long, so the whole link
-            dropped to the next line and left the triangle alone on a row of its own, which reads
-            as an empty nav entry. Capped, it stays beside the triangle and wraps inside itself.
-            */
-            boxSizing: 'border-box',
-            maxWidth: 'calc(100% - 1.5em)',
-            verticalAlign: 'top',
-        },
+        ...navSectionStyleSpec,
         // Declarative header link list — shown for no-JS, removed on hydration.
         '.doc-navbar': {
             listStyle: 'none',

package/dist/doc-system/nav-styles.d.ts

@@ -0,0 +1,2 @@
+import { type XinStyleSheet } from 'tosijs';
+export declare const navSectionStyleSpec: XinStyleSheet;

package/dist/doc-system/nav-styles.js

@@ -0,0 +1,65 @@
+import { vars } from 'tosijs';
+/*
+The doc nav's collapsible sections, in a module of their own because two places need them:
+the site stylesheet (`docSystemStyleSpec`), which paints the pre-rendered nav before anything
+hydrates, and `createDocBrowser`, which injects them itself. A browser created outside
+<tosi-doc-system> (an embedded, memory-routed one) never gets the site stylesheet, and
+before #3520 it did not need it: native <details> collapsed with no CSS at all.
+*/
+export const navSectionStyleSpec = {
+    '.doc-nav .nav-branch > ul': {
+        paddingLeft: vars.spacing,
+    },
+    /*
+      A section is a toggle button BESIDE its link (#3520). It was <details><summary><a>, a link
+      inside a control, which a screen reader announces as one and loses the other (axe
+      `nested-interactive`), and its marker was under the 24px target size WCAG 2.2 asks.
+      A closed section collapses only when JavaScript is running (`tosi-js` is set on <html>
+      before first paint; a nav `createDocBrowser` built is `.-live`): without it nothing
+      could open the section, so every one stays expanded.
+      */
+    'html.tosi-js .doc-nav .nav-branch:not(.-open) > ul, .doc-nav.-live .nav-branch:not(.-open) > ul': {
+        display: 'none',
+    },
+    '.doc-nav .nav-branch-head': {
+        display: 'flex',
+        alignItems: 'flex-start',
+    },
+    '.doc-nav .nav-toggle': {
+        flex: '0 0 auto',
+        minWidth: '24px',
+        minHeight: '24px',
+        padding: 0,
+        margin: 0,
+        border: 'none',
+        background: 'transparent',
+        boxShadow: 'none',
+        cursor: 'pointer',
+        color: vars.brandColor,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        alignSelf: 'stretch',
+        maxHeight: vars.lineHeight,
+    },
+    // A disclosure triangle, pointing right when closed and down when open.
+    '.doc-nav .nav-toggle::before': {
+        content: "''",
+        borderStyle: 'solid',
+        borderColor: 'transparent transparent transparent currentcolor',
+        borderWidth: '0.3em 0 0.3em 0.5em',
+        transition: 'transform 0.15s ease-out',
+    },
+    '.doc-nav .nav-branch.-open > .nav-branch-head > .nav-toggle::before': {
+        transform: 'rotate(90deg)',
+    },
+    // Without JavaScript every section is open and nothing could close one, so the toggle is
+    // hidden: kept in the layout, out of the tab order and the accessibility tree.
+    'html:not(.tosi-js) .doc-nav:not(.-live) .nav-toggle': {
+        visibility: 'hidden',
+    },
+    '.doc-nav .nav-branch-head > .doc-link': {
+        flex: '1 1 auto',
+        minWidth: 0,
+    },
+};

package/dist/doc-system/site/dev-server.d.ts

@@ -179,4 +179,10 @@ export declare function isCompressible(filePath: string): boolean;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;
     build?: () => unknown | Promise<unknown>;
+    /**
+     * Build once on start (default `true`). Pass `false` only when the caller has just
+     * built, as `bin/dev.ts` does; otherwise the server serves whatever the LAST run
+     * left in the output dir, built from whatever config that run had (#3524).
+     */
+    initialBuild?: boolean;
 }): Promise<void>;

package/dist/doc-system/site/dev-server.js

@@ -1796,6 +1796,15 @@ export async function devServer(config, opts = {}) {
             }
             void rebuild();
         });
+        /*
+        Build on start (#3524). The documented one-liner, `… : devServer(config)`, never built:
+        it served the previous run's output, so a config edit (a theme accent, an ePub cover)
+        showed nothing until some watched file changed, and nothing said the page was stale.
+        Started without awaiting, so the port binds at once; requests during the build fall
+        back to the last good tree, as they do for every rebuild.
+        */
+        if (opts.initialBuild !== false)
+            void rebuild();
     }
     /*
     ── dependency audit (NON-BLOCKING — the port comes up first) ─────────────────

package/dist/doc-system/site/generate-site.d.ts

@@ -105,6 +105,13 @@ export interface GenerateSiteConfig {
     /** extra lines injected into every <head> (favicon, analytics, etc.) */
     headExtra?: string;
 }
+/**
+ * A section's disclosure toggle. A real button BESIDE the link, not a `<summary>` around it:
+ * a link inside a summary is a control inside a control, which a screen reader announces as
+ * one and loses the other (axe `nested-interactive`, #3520). Named by the section title, so
+ * it reads "Components, expanded, button". The hydrated nav builds the same markup.
+ */
+export declare function navToggleHtml(title: string, listId: string, open: boolean): string;
 /**
  * Prefix a root-relative path with basePath. No-op for '/', empty, protocol-
  * relative (`//…`), or absolute (`https://…`) URLs.

package/dist/doc-system/site/generate-site.js

@@ -25,10 +25,20 @@ const escapeAttr = (s) => s
     .replace(/'/g, ''');
 const escapeText = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 /**
- * Build the hierarchical nav as nested <details>. Parents render as
- * <details><summary><a>…</a></summary><ul>…children…</ul></details>, with the
- * <details> on the path to `currentFilename` opened. `currentFilename` gets
- * aria-current. Crawlable + no-JS: every node is a real <a>.
+ * A section's disclosure toggle. A real button BESIDE the link, not a `<summary>` around it:
+ * a link inside a summary is a control inside a control, which a screen reader announces as
+ * one and loses the other (axe `nested-interactive`, #3520). Named by the section title, so
+ * it reads "Components, expanded, button". The hydrated nav builds the same markup.
+ */
+export function navToggleHtml(title, listId, open) {
+    return `<button type="button" class="nav-toggle" aria-expanded="${open}" aria-controls="${escapeAttr(listId)}" aria-label="${escapeAttr(title)}"></button>`;
+}
+/**
+ * Build the hierarchical nav. Parents render as
+ * <li class="nav-branch"><div class="nav-branch-head"><button/><a/></div><ul/></li>, with
+ * `-open` on the sections on the path to `currentFilename`. `currentFilename` gets
+ * aria-current. Crawlable + no-JS: every node is a real <a>, and without JS (no `tosi-js`
+ * class on <html>) no section collapses, since nothing could open it.
  */
 function navHtml(docs, slugMap, currentFilename, depth) {
     const roots = buildNavTree(docs, slugMap);
@@ -48,13 +58,15 @@ function navHtml(docs, slugMap, currentFilename, depth) {
         if (node.children.length === 0) {
             return `${indent}<li>${link}</li>`;
         }
-        const isOpen = open.has(node.doc.filename) ? ' open' : '';
+        const isOpen = open.has(node.doc.filename);
         const kids = node.children
             .map((c) => renderNode(c, indent + '  '))
             .join('\n');
-        return (`${indent}<li><details${isOpen}><summary>${link}</summary>\n` +
-            `${indent}<ul>\n${kids}\n${indent}</ul>\n` +
-            `${indent}</details></li>`);
+        // Prefixed so it cannot collide with a heading id (`## Nav Components` → nav-components).
+        const listId = `tosi-nav-${node.slug || 'home'}`;
+        return (`${indent}<li class="nav-branch${isOpen ? ' -open' : ''}">` +
+            `<div class="nav-branch-head">${navToggleHtml(node.doc.title, listId, isOpen)}${link}</div>\n` +
+            `${indent}<ul id="${escapeAttr(listId)}">\n${kids}\n${indent}</ul></li>`);
     };
     const items = roots.map((n) => renderNode(n, '    ')).join('\n');
     return `  <nav class="doc-nav" aria-label="Documentation">\n  <ul>\n${items}\n  </ul>\n  </nav>`;
@@ -236,6 +248,12 @@ at = slugMap[doc.filename] ?? '') {
        until the bundle lands and sets body.darkmode. CSS alone can't do this: an explicit theme
        choice lives in localStorage. Mirrors applyThemePrefs() (doc-system.ts) — keep the two in
        step. Fails safe: any error leaves the light default.
+  
+    3. It marks <html> with `tosi-js`, which is what lets a closed nav section collapse (#3520):
+       without JavaScript nothing could open one, so none collapses. And it opens and closes the
+       static nav's sections until the doc system upgrades, so a reader on a slow bundle, or one
+       whose bundle failed, can still use them. Once the element is defined the hydrated nav
+       handles its own toggles and this stands down, so a click never toggles twice.
     */
     return `<!DOCTYPE html>
 <html lang="${escapeAttr(lang)}">
@@ -243,6 +261,14 @@ at = slugMap[doc.filename] ?? '') {
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <script>
+    document.documentElement.classList.add('tosi-js')
+    document.addEventListener('click', function (e) {
+      if (customElements.get('tosi-doc-system')) return
+      var b = e.target.closest && e.target.closest('.doc-nav .nav-toggle')
+      if (!b) return
+      var open = b.closest('.nav-branch').classList.toggle('-open')
+      b.setAttribute('aria-expanded', String(open))
+    })
     try {
       var p = JSON.parse(localStorage.getItem('tosi-doc-system-prefs') || '{}')
       var t = p.theme || 'system'