tosijs-ui 1.16.41 → 1.17.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 1.17.0-beta.2
+
+> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
+> on 1.16.41. Fixes from Learn 3D's first run of beta.1.
+
+- **Accessibility mode: headings in a blockquote or list shift with the rest of the page
+  (#3576).** A sidebar's `> ####` under `###` sections stayed an `<h4>` under the new `<h2>`s, so
+  the build reported a skipped level and DAISY Ace failed the ePub on heading order. A heading
+  inside a blockquote still never becomes the page's title.
+- **DAISY Ace is found on `PATH` (#3577).** The docs said `bun add -d @daisy/ace`, which brings
+  Electron and Puppeteer into the project, and their advisories then failed the build's own
+  dependency audit. Install it globally (`npm install -g @daisy/ace`) instead; the build looks in
+  the project first, then on `PATH`.
+- **The axe audit is about twice as fast, and audits the page a reader gets (#3585).** Pages are
+  audited four at a time (this site: 80s to 43s). Each is audited once it stops adding elements,
+  rather than after a fixed 300ms, which on a busy machine caught pages half-built. And the
+  audit no longer starts the doc browser's background test runner, which runs on localhost and
+  never on a deployed site. `TOSIJS_A11Y_AUDIT=off` skips the audit and the Ace check for one
+  build while the mode stays on; the ePub then claims no conformance.
+- **Section stubs are not written where they cannot be read, or mid-edit (#3584).** A page whose
+  `parent` names a missing doc gets a stub section doc in `sectionsDir`. When `sectionsDir` is
+  outside every `docPaths` entry, the build now warns and writes nothing, since the stub would
+  never be read back. Stubs are created only on the first build in a process, so a parent that
+  disappears for a second during a rename no longer leaves files behind. Each stub written is
+  named in the build output.
+- **`preview.host` is optional, and the preview docs no longer say `host` is required (#3586).**
+  The type has allowed a config with only `preview.tunnel` since 1.10.0, but the doc comment and
+  the reference table still said so. `as any` casts written for it can go.
+
+### 1.17.0-beta.1 (prerelease detail)
+
+> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
+> on 1.16.41. It carries the accessibility half of 1.17.0; the SEO work and #245/#246 follow.
+
+- **An opt-in accessibility mode for doc sites (#3521).** `accessibility: 'wcag22-aa'` in the
+  site config makes the build do what it can decide on its own and report what it cannot, on the
+  site, in print and in the ePub:
+  - an image alone in its paragraph, followed by an italic-only paragraph, renders as a
+    `<figure>` with that text as its `<figcaption>`;
+  - every page has exactly one `<h1>`, its title: a page's first heading is promoted when its
+    title came from it, a later `#` becomes `##`, and the rest shift to start at `##`;
+  - the build lists, by file and line, each image with no alt text and no caption, each heading
+    that skips a level, and each link named "here" or the like, and fails on them under `strict`.
+
+  Off by default; a site that does not set it renders exactly as before.
+- **The mode audits the built site with axe.** A full build opens every page in Chromium and runs
+  axe-core's WCAG 2.2 AA rules, listing each failure by page, rule and element and failing under
+  `strict`. It needs `playwright` and `axe-core` in your project; without them the build says the
+  audit did not run rather than reporting a pass. Never under a dev server.
+- **Accessible ePubs (#3522).** In the mode, the book's package document declares its access
+  modes, features, hazards and a summary (EPUB Accessibility 1.1), derived from the build: it
+  claims alternative text only when every image has alt text or a caption. Conformance to WCAG
+  2.2 AA is claimed only when DAISY Ace, installed in your project, has checked the finished book
+  and passed it. `epub: { accessibility: { summary, hazards, certifiedBy } }` overrides the
+  defaults. Checked against real Ace: this site's own book passes.
+- **Every ePub, mode or not: the right language, readable links, landmarks.** Each chapter, the
+  nav, the contents and the cover said `xml:lang="en"` whatever the book's language, and the
+  package said none, so a reading system pronounced a French book as English. Links were
+  `#0088cc` (3.9:1 on white) and marked by colour alone; they are now 6.6:1 and underlined.
+  The nav gains a landmarks list (cover, contents, start of the text) and its table of contents
+  `role="doc-toc"`.
+- **`altText`: a hook that supplies alt text for undescribed images.** With the mode on, it is
+  called for each image the build would report, and its answer becomes that image's alt text in
+  the built site, `docs.json` and the ePub. It never writes a source file. It runs on every
+  build, so cache anything slow by `src`.
+- **The doc-site search trigger's name contains its visible text (#3569).** Its `aria-label`
+  was "Search (⌘K)" beside visible text "Search ⌘K", which fails WCAG 2.5.3 (a voice-control user
+  says what they see) on every page of every doc site. A `<tosi-palette>` field trigger is now
+  named by its text, an icon trigger keeps an `aria-label`, and the shortcut is announced through
+  `aria-keyshortcuts`. The frame's axe test now runs every WCAG 2.2 A and AA rule, not four.
+- **The header's site name is no longer a heading.** It was an `<h2>` above every page's own
+  `<h1>`, so it was each page's first heading. It is now `<span class="site-name">` and looks the
+  same; site CSS that styled `header h2` should target `header .site-name`.
+
 ## 1.16.41
 
 - **A `noindex` page is left out of `llms.txt`.** The sitemap and the markdown copies already

package/dist/doc-browser.d.ts

@@ -1,3 +1,4 @@
+import { type AccessibilityMode } from './doc-system/render.js';
 import { TestResults } from './live-example/test-harness.js';
 import { type ExamplePolicy } from './doc-system/example-policy.js';
 export declare const hasTestBlock: (text: string | undefined, policy?: ExamplePolicy) => boolean;
@@ -123,6 +124,11 @@ export interface DocBrowserOptions {
      * strings, like every other piece of the doc system's own text.
      */
     searchPlaceholder?: string;
+    /**
+     * `SiteConfig.accessibility` (#3521): render figures with captions and exactly one `<h1>`
+     * per page, as the static build does, so a hydrated page matches it.
+     */
+    accessibility?: AccessibilityMode;
     /**
      * Header-bar links. When provided, these replace the legacy `projectLinks` icon
      * set in the header (each renders as an icon if `icon` names a known icon, else

package/dist/doc-browser.js

@@ -103,7 +103,7 @@ import { elements, vars, varDefault, bindings, getListItem, tosi, StyleSheet, }
 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 { renderDocMarkdown, } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
 import { unsettledExamples, tallyExamples, closePage, } from './doc-system/test-completion.js';
 import { LiveExample, testManager, pageTestCount, enableTests, disableTests, } from './live-example.js';
@@ -149,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, ul, li } = elements;
+const { div, span, a, header, button, template, img, ul, li } = elements;
 /*
 Test colors, and the text color that goes ON each — because contrast is a PAIR.
 
@@ -395,7 +395,7 @@ 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', searchPlaceholder = 'Search', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', searchPlaceholder = 'Search', accessibility, navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
     // window.history/location, so an embedded or nested browser can't hijack the
     // host page's URL (or recurse into it).
@@ -906,7 +906,10 @@ export function createDocBrowser(options) {
                 alignItems: 'center',
                 borderBottom: 'none',
             },
-        }, logoMark(logo, projectLinks), h2(projectName)));
+        }, logoMark(logo, projectLinks), 
+        // Not a heading: the site name above every page made it each page's first heading,
+        // an <h2> ahead of the page's own <h1> (#3521).
+        span({ class: 'site-name' }, projectName)));
     }
     headerContent.push(span({ class: 'elastic' }), searchBox);
     // A header link renders as an icon (if `icon` names a known icon) or its label.
@@ -1054,6 +1057,8 @@ export function createDocBrowser(options) {
             docContent.innerHTML = renderDocMarkdown(doc.text, {
                 bakes: doc.bakes ? new Map(doc.bakes) : undefined,
                 wikilinks,
+                accessible: !!accessibility,
+                title: doc.title,
             });
         }
         /*
@@ -1345,7 +1350,7 @@ export function createDocBrowser(options) {
             return;
         editUI.view = view;
         if (view === 'preview') {
-            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks });
+            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks, accessible: !!accessibility, title: editUI.doc.title });
             rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
             focusableCodeBlocks(docContent);

package/dist/doc-system/book-html.d.ts

@@ -8,7 +8,7 @@ export interface BookDoc {
     parent?: string;
     hidden?: boolean;
 }
-export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/*\nPrism token colours for the book \u2014 a LIGHT palette, deliberately distinct from the site's.\n\nThe site has TWO palettes, one per mode. A book has one background and it is light: the\npre rule above is #f6f8fa, an ePub reader may impose white or sepia, and paper is paper.\nReusing the site palette here would be light-on-light \u2014 invisible body text dressed as syntax\nhighlighting, which is the exact failure a nested diff hit in tosijs-ui#143.\n\nContrast-checked against #f6f8fa; the comment green is the weakest at ~4.6:1, still above\nWCAG AA for body text. Colours are literal rather than custom properties because this\nstylesheet ships inside an ePub, where custom properties are not reliably supported.\n\nNO BACKTICKS in this comment: it lives inside a JS template literal, so one would end the\nstring and drop the rest of the stylesheet into code. (It did. Same shape as a block comment\nending a doc comment early \u2014 punctuation that means something to the container.)\n*/\n.token.comment, .token.prolog, .token.cdata { color: #5c6f5c; font-style: italic; }\n.token.punctuation { color: #666; }\n.token.string, .token.char, .token.attr-value, .token.regex { color: #a03030; }\n.token.number, .token.boolean, .token.constant { color: #0b7285; }\n.token.keyword, .token.important, .token.atrule { color: #0a5bb5; }\n.token.function, .token.class-name { color: #7a4b00; }\n.token.operator, .token.entity, .token.url { color: #444; }\n.token.tag, .token.selector, .token.builtin { color: #0a6b52; }\n.token.attr-name, .token.property { color: #2a5db0; }\n.token.deleted { color: #b02020; }\n.token.inserted { color: #2a6b2a; }\n.token.bold { font-weight: bold; }\n.token.italic { font-style: italic; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
+export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\n/* 6.6:1 on white, and underlined: colour alone does not mark a link in running text (#3522, DAISY Ace) */\na { color: #0a5bb5; text-decoration: underline; text-underline-offset: 0.15em; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/*\nPrism token colours for the book \u2014 a LIGHT palette, deliberately distinct from the site's.\n\nThe site has TWO palettes, one per mode. A book has one background and it is light: the\npre rule above is #f6f8fa, an ePub reader may impose white or sepia, and paper is paper.\nReusing the site palette here would be light-on-light \u2014 invisible body text dressed as syntax\nhighlighting, which is the exact failure a nested diff hit in tosijs-ui#143.\n\nContrast-checked against #f6f8fa; the comment green is the weakest at ~4.6:1, still above\nWCAG AA for body text. Colours are literal rather than custom properties because this\nstylesheet ships inside an ePub, where custom properties are not reliably supported.\n\nNO BACKTICKS in this comment: it lives inside a JS template literal, so one would end the\nstring and drop the rest of the stylesheet into code. (It did. Same shape as a block comment\nending a doc comment early \u2014 punctuation that means something to the container.)\n*/\n.token.comment, .token.prolog, .token.cdata { color: #5c6f5c; font-style: italic; }\n.token.punctuation { color: #666; }\n.token.string, .token.char, .token.attr-value, .token.regex { color: #a03030; }\n.token.number, .token.boolean, .token.constant { color: #0b7285; }\n.token.keyword, .token.important, .token.atrule { color: #0a5bb5; }\n.token.function, .token.class-name { color: #7a4b00; }\n.token.operator, .token.entity, .token.url { color: #444; }\n.token.tag, .token.selector, .token.builtin { color: #0a6b52; }\n.token.attr-name, .token.property { color: #2a5db0; }\n.token.deleted { color: #b02020; }\n.token.inserted { color: #2a6b2a; }\n.token.bold { font-weight: bold; }\n.token.italic { font-style: italic; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #0a5bb5; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
 export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-cover { display: block; margin: 0 auto; max-width: 100%; max-height: 100vh; page-break-after: always; break-inside: avoid; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
 export declare function escapeHtml(s: string): string;
 export declare function slugify(s: string): string;
@@ -27,6 +27,8 @@ export interface BookHtmlOptions {
     /** full stylesheet (defaults to DEFAULT_BOOK_CSS + PRINT_CSS) */
     css?: string;
     lang?: string;
+    /** `SiteConfig.accessibility`: figures and one `<h1>` per chapter (#3521) */
+    accessible?: boolean;
     /** inject a script that opens the print dialog once the page has loaded */
     autoPrint?: boolean;
 }

package/dist/doc-system/book-html.js

@@ -28,7 +28,8 @@ h1 { font-size: 1.8em; }
 h2 { font-size: 1.4em; }
 h3 { font-size: 1.2em; }
 p { margin: 0.6em 0; }
-a { color: #08c; text-decoration: none; }
+/* 6.6:1 on white, and underlined: colour alone does not mark a link in running text (#3522, DAISY Ace) */
+a { color: #0a5bb5; text-decoration: underline; text-underline-offset: 0.15em; }
 ul, ol { margin: 0.6em 0; padding-left: 1.4em; }
 blockquote {
   margin: 0.8em 0;
@@ -96,7 +97,7 @@ ol.toc li { margin: 0.3em 0; }
 ol.toc > li > a { font-weight: bold; }
 /* per-example "run this live" deep link */
 .example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }
-.example-live-link a { color: #08c; font-weight: bold; }
+.example-live-link a { color: #0a5bb5; font-weight: bold; }
 /* footnotes / endnotes + wikilinks */
 sup.footnote-ref { font-size: 0.7em; line-height: 0; }
 sup.footnote-ref a { text-decoration: none; }
@@ -155,6 +156,8 @@ export function buildBookHtml(docs, opts) {
     const chapters = flatten(roots)
         .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)), {
         wikilinks,
+        accessible: opts.accessible,
+        title: node.doc.title,
     })}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>

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

@@ -393,9 +393,13 @@ export function docSystemStyleSpec(theme = {}) {
             margin: `${vars.spacing} 0 ${vars.spacing200}`,
             padding: 0,
         },
-        'header h2': {
+        'header .site-name': {
             color: vars.brandTextColor,
             whiteSpace: 'nowrap',
+            fontWeight: '700',
+            fontSize: 'calc(var(--font-size) * var(--h2-scale))',
+            lineHeight: 'calc(var(--line-height) * var(--h2-scale))',
+            margin: 'calc(var(--spacing) * var(--h2-scale)) 0',
         },
         h2: {
             color: vars.brandColor,

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

@@ -332,11 +332,13 @@ export class TosiDocSystem extends withAttributes({
                 let projectName = '';
                 let bookVolumes;
                 let ebooks;
+                let accessible = false;
                 try {
                     const parsed = JSON.parse(this.config || '{}');
                     projectName = parsed.projectName || '';
                     bookVolumes = parsed.bookVolumes || undefined;
                     ebooks = parsed.ebooks;
+                    accessible = !!parsed.accessibility;
                 }
                 catch {
                     // ignore — fall through to document.title
@@ -372,6 +374,7 @@ export class TosiDocSystem extends withAttributes({
                             title: bookTitle,
                             cover: bookCover,
                             autoPrint: false,
+                            accessible,
                         }));
                         win.document.close();
                         /*
@@ -609,6 +612,7 @@ export class TosiDocSystem extends withAttributes({
             logo: config.logo,
             navbarLinks: navbarLinks.length ? navbarLinks : undefined,
             searchPlaceholder: config.searchPlaceholder,
+            accessibility: config.accessibility,
             contentElement,
         });
         // Add the settings (theme + language) menu — except in a nested demo, where

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

@@ -3,12 +3,31 @@ export interface ExampleBake {
     js: string;
 }
 export type ExampleBakes = Map<string, ExampleBake>;
+/** `SiteConfig.accessibility`. One level for now; the name says which standard it targets. */
+export type AccessibilityMode = 'wcag22-aa';
+/**
+ * The accessibility mode's token rewrites (#3521), exported so the build's report reads exactly
+ * the structure the page renders.
+ */
+export declare function accessibleTokens(tokens: any[], title?: string): any[];
 export declare function unwrapLoneCustomElements(html: string): string;
 export declare function renderDocMarkdown(text: string, opts?: {
     bakes?: ExampleBakes;
     /** the corpus's `wikilinkTargets`; without it a `[[target]]` is slugified as written */
     wikilinks?: Map<string, string>;
+    /**
+     * The accessibility mode (#3521): figures with captions, and exactly one `<h1>`. `title` is
+     * the page title, rendered as that `<h1>` when the markdown has none.
+     */
+    accessible?: boolean;
+    title?: string;
 }): string;
+/**
+ * A doc's tokens as the accessibility mode renders them, for the build's report: the same
+ * lexer and the same rewrites as `renderDocMarkdown`, so the report and the page cannot
+ * disagree about what is a figure or which heading is the `<h1>`.
+ */
+export declare function accessibleDocTokens(text: string, title?: string): any[];
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.
  * Skips the title heading, code fences, tables, quotes, html and image/link-only

package/dist/doc-system/render.js

@@ -10,13 +10,147 @@ give that example a stable anchor — see the docMarked renderer below.
 */
 import { Marked, Renderer } from 'marked';
 import { parseFenceInfo } from './example-policy.js';
-import { HeadingIds, headingSlug } from './heading-id.js';
+import { HeadingIds, headingSlug, headingText } from './heading-id.js';
 import { pathForSlug, slugify } from './routing.js';
 const baseRenderer = new Renderer();
 let currentBakes;
 let currentWikilinks;
 // Per-parse, reset in `preprocess` below (same pattern as the footnote state).
 let headingIds = new HeadingIds();
+let currentA11y;
+const isBlank = (t) => (t.type === 'text' && !String(t.raw).trim()) || t.type === 'br';
+/** The image token of a paragraph whose only content is one image, else undefined. */
+function loneImage(tokens) {
+    const content = tokens.filter((t) => !isBlank(t));
+    return content.length === 1 && content[0].type === 'image'
+        ? content[0]
+        : undefined;
+}
+/** The em token of a paragraph whose only content is italic text, else undefined. */
+function loneEmphasis(tokens) {
+    const content = tokens.filter((t) => !isBlank(t));
+    return content.length === 1 && content[0].type === 'em'
+        ? content[0]
+        : undefined;
+}
+function figureFrom(paragraph) {
+    // `![…](…)` and `*caption*` on consecutive lines are one paragraph to marked.
+    const content = paragraph.tokens.filter((t) => !isBlank(t));
+    if (content.length === 2 &&
+        content[0].type === 'image' &&
+        content[1].type === 'em')
+        return {
+            type: 'figure',
+            raw: paragraph.raw,
+            image: content[0],
+            caption: content[1],
+        };
+    return undefined;
+}
+function withFigures(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'blockquote' && Array.isArray(token.tokens)) {
+            token.tokens = withFigures(token.tokens);
+        }
+        if (token.type !== 'paragraph') {
+            out.push(token);
+            continue;
+        }
+        const joined = figureFrom(token);
+        if (joined) {
+            out.push(joined);
+            continue;
+        }
+        const image = loneImage(token.tokens);
+        let next = i + 1;
+        while (tokens[next]?.type === 'space')
+            next += 1;
+        const caption = image &&
+            tokens[next]?.type === 'paragraph' &&
+            loneEmphasis(tokens[next].tokens);
+        if (caption) {
+            out.push({
+                type: 'figure',
+                raw: tokens
+                    .slice(i, next + 1)
+                    .map((t) => t.raw)
+                    .join(''),
+                image,
+                caption,
+            });
+            i = next;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+// Every heading, including those in blockquotes and lists: a sidebar's `> ####` shifts with the
+// page's own headings, or it lands a level too deep (#3576).
+function allHeadings(tokens, out = []) {
+    for (const t of tokens) {
+        if (t.type === 'heading')
+            out.push(t);
+        else if (t.type === 'blockquote')
+            allHeadings(t.tokens ?? [], out);
+        else if (t.type === 'list')
+            for (const item of t.items ?? [])
+                allHeadings(item.tokens ?? [], out);
+    }
+    return out;
+}
+function withOneTitle(tokens, title) {
+    // Only a top-level heading can be the page's title.
+    const headings = tokens.filter((t) => t.type === 'heading');
+    const nested = allHeadings(tokens);
+    /*
+    A page with no `#` takes its title from its first heading, whatever its level, so that
+    heading IS the title: promote it rather than print the same words twice.
+    */
+    const lead = headings[0];
+    const first = headings.find((t) => t.depth === 1) ??
+        (lead && title && headingText(lead).trim() === title.trim()
+            ? lead
+            : undefined);
+    // The shift comes from the sub-headings as written; a demoted `#` is not one of them.
+    const below = nested
+        .filter((h) => h !== first && h.depth > 1)
+        .map((h) => h.depth);
+    const shift = below.length ? Math.min(...below) - 2 : 0;
+    if (first)
+        first.depth = 1;
+    for (const h of nested) {
+        if (h === first)
+            continue;
+        if (h.depth === 1)
+            h.depth = 2;
+        else if (shift > 0)
+            h.depth -= shift;
+    }
+    if (!first && title)
+        return [
+            {
+                type: 'heading',
+                raw: '',
+                depth: 1,
+                text: title,
+                tokens: [
+                    { type: 'text', raw: title, text: escapeHtml(title), escaped: true },
+                ],
+            },
+            ...tokens,
+        ];
+    return tokens;
+}
+/**
+ * The accessibility mode's token rewrites (#3521), exported so the build's report reads exactly
+ * the structure the page renders.
+ */
+export function accessibleTokens(tokens, title) {
+    return withOneTitle(withFigures(tokens), title);
+}
 const docMarked = new Marked();
 docMarked.use({
     renderer: {
@@ -86,6 +220,13 @@ let footnoteDefs = new Map();
 let footnoteOrder = [];
 docMarked.use({
     hooks: {
+        processAllTokens(tokens) {
+            if (!currentA11y)
+                return tokens;
+            const rewritten = accessibleTokens([...tokens], currentA11y.title);
+            // A TokensList carries `links` (reference definitions); keep it.
+            return Object.assign(rewritten, { links: tokens.links });
+        },
         preprocess(markdown) {
             footnoteDefs = new Map();
             footnoteOrder = [];
@@ -106,6 +247,15 @@ docMarked.use({
         },
     },
     extensions: [
+        {
+            // Built only by `accessibleTokens` above; there is no syntax of its own to tokenize.
+            name: 'figure',
+            renderer(token) {
+                const image = this.parser.parseInline([token.image]);
+                const caption = this.parser.parseInline(token.caption.tokens);
+                return `<figure>${image}<figcaption>${caption}</figcaption></figure>\n`;
+            },
+        },
         {
             // [[slug]] / [[slug|label]] → link to /slug/. Not matched inside code spans
             // (Marked tokenizes those first). Given the corpus's `wikilinkTargets`, a target is
@@ -209,14 +359,24 @@ export function unwrapLoneCustomElements(html) {
 export function renderDocMarkdown(text, opts = {}) {
     currentBakes = opts.bakes;
     currentWikilinks = opts.wikilinks;
+    currentA11y = opts.accessible ? { title: opts.title } : undefined;
     try {
         return unwrapLoneCustomElements(docMarked.parse(text));
     }
     finally {
         currentBakes = undefined;
         currentWikilinks = undefined;
+        currentA11y = undefined;
     }
 }
+/**
+ * A doc's tokens as the accessibility mode renders them, for the build's report: the same
+ * lexer and the same rewrites as `renderDocMarkdown`, so the report and the page cannot
+ * disagree about what is a figure or which heading is the `<h1>`.
+ */
+export function accessibleDocTokens(text, title) {
+    return accessibleTokens([...docMarked.lexer(text)], title);
+}
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.
  * Skips the title heading, code fences, tables, quotes, html and image/link-only

package/dist/doc-system/site/a11y-audit-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/doc-system/site/a11y-audit-cli.js

@@ -0,0 +1,139 @@
+/*
+The accessibility mode's axe audit, run in a child process (#3521, item 6).
+
+Serves the built site, opens every page in Chromium, waits for it to hydrate, and runs axe-core
+with the WCAG 2.0–2.2 A and AA rules. A child for the same reason as the ePub: a browser and
+everything it strands go back to the OS on exit, and a build process may live for days.
+
+Playwright and axe-core are the ADOPTER's: resolved from the project, never dependencies of
+tosijs-ui. When either is missing, or Chromium is not installed, it says which and exits
+NOT_RUN_EXIT, so the build can say the audit did not run instead of reporting a pass.
+
+  bun a11y-audit-cli.ts <payload.json>   # payload = { outputDir, basePath, pages }
+  stdout: one JSON line, { violations: AxeFinding[] }
+
+Build-time only. Never import this from browser code.
+*/
+import * as path from 'path';
+import { createRequire } from 'module';
+import { existsSync } from 'fs';
+import { NOT_RUN_EXIT, AXE_TAGS } from './a11y-audit.js';
+const payloadPath = process.argv[2];
+const { outputDir, basePath, pages } = JSON.parse(await Bun.file(payloadPath).text());
+const notRun = (why) => {
+    console.error(why);
+    process.exit(NOT_RUN_EXIT);
+};
+// Resolve from the project, where an adopter installs them, not from this package.
+const projectRequire = createRequire(path.resolve('package.json'));
+let axePath = '';
+let playwright;
+try {
+    axePath = projectRequire.resolve('axe-core/axe.min.js');
+}
+catch {
+    notRun('axe-core is not installed in this project (bun add -d axe-core)');
+}
+try {
+    playwright = await import(projectRequire.resolve('playwright'));
+}
+catch {
+    notRun('playwright is not installed in this project (bun add -d playwright)');
+}
+const root = path.resolve(outputDir);
+const prefix = (basePath || '').replace(/\/$/, '');
+const server = Bun.serve({
+    port: 0,
+    fetch(request) {
+        let pathname = decodeURIComponent(new URL(request.url).pathname);
+        if (prefix && pathname.startsWith(prefix))
+            pathname = pathname.slice(prefix.length) || '/';
+        if (pathname.endsWith('/'))
+            pathname += 'index.html';
+        const file = path.join(root, pathname);
+        if (!file.startsWith(root) || !existsSync(file))
+            return new Response('not found', { status: 404 });
+        return new Response(Bun.file(file));
+    },
+});
+let browser;
+try {
+    browser = await playwright.chromium.launch();
+}
+catch (error) {
+    server.stop(true);
+    notRun(`Chromium could not be launched (bunx playwright install chromium): ${error.message.split('\n')[0]}`);
+}
+/*
+Pages are audited a few at a time, each in its own tab: one at a time took Learn 3D's 126 pages
+to ~73s (#3585). Results are kept in page order, so the report reads the same either way.
+*/
+const CONCURRENCY = 4;
+const perPage = [];
+try {
+    const context = await browser.newContext();
+    /*
+    The page a reader gets: served from localhost, the doc browser would start its background test
+    runner, whose hidden frames and badges no deployed site has.
+    */
+    await context.addInitScript(() => localStorage.setItem('tosijs-ui-tests-enabled', 'false'));
+    let next = 0;
+    const worker = async () => {
+        const page = await context.newPage();
+        while (next < pages.length) {
+            const index = next++;
+            const pagePath = pages[index];
+            await page.goto(`http://localhost:${server.port}${prefix}${pagePath}`, {
+                waitUntil: 'networkidle',
+            });
+            // Audit the page a reader uses: hydrated when the bundle loads, static if it does not.
+            if (await page.$('tosi-doc-system'))
+                await page
+                    .waitForFunction(() => customElements.get('tosi-doc-system'), null, {
+                    timeout: 10_000,
+                })
+                    .catch(() => undefined);
+            /*
+            Then until no element has been added or removed for half a second (at most five): live examples render
+            after hydration, and a fixed pause audited a busy machine's pages half-built, so the
+            findings changed from run to run.
+            */
+            await page.evaluate(() => new Promise((resolve) => {
+                let timer = setTimeout(done, 500);
+                const deadline = setTimeout(done, 5000);
+                const observer = new MutationObserver(() => {
+                    clearTimeout(timer);
+                    timer = setTimeout(done, 500);
+                });
+                function done() {
+                    observer.disconnect();
+                    clearTimeout(timer);
+                    clearTimeout(deadline);
+                    resolve();
+                }
+                // Elements arriving, not attributes: an animation changes a style forever.
+                observer.observe(document, { subtree: true, childList: true });
+            }));
+            await page.addScriptTag({ path: axePath });
+            const found = await page.evaluate(async (tags) => {
+                const result = await window.axe.run(document, {
+                    runOnly: { type: 'tag', values: tags },
+                });
+                return result.violations.map((v) => ({
+                    rule: v.id,
+                    impact: v.impact,
+                    help: v.help,
+                    targets: v.nodes.map((n) => n.target.join(' ')),
+                }));
+            }, AXE_TAGS);
+            perPage[index] = found.map((v) => ({ page: pagePath, ...v }));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, pages.length) }, worker));
+}
+finally {
+    await browser.close();
+    server.stop(true);
+}
+const violations = perPage.flat();
+console.log(JSON.stringify({ violations }));