Second batch of accessibility, content and tooling improvements.

.github/workflows/checks.yml

@@ -125,6 +125,89 @@ jobs:
       # the point, and the deploy workflow has a site to ship.
       - name: Verify the build's own link checker (check_links_diff.mjs)
         run: node scripts/check_links_diff.mjs --case fixture-built --case fixture-built-offline --a script --b fused
+      # The publish allowlist (builder/publish-policy.mjs) is enforced
+      # inside the build above, so a green build already says nothing
+      # unpublishable is in docs/. It does NOT say the allowlist still
+      # refuses anything: one widened until it refuses nothing reports the
+      # same clean pass. This asserts the refusals against named probes --
+      # a stray .bak, a .pem, a scratch .md with no frontmatter. No
+      # browser, no built tree, ~40 ms.
+      - name: Verify the publish allowlist (check_publish_policy.mjs)
+        run: node scripts/check_publish_policy.mjs
+      # The two gate lists on Tools.md against the wrappers that run
+      # them, plus every gate count stated in prose in README.md or
+      # under docs/Documentation/. Documented gate counts have rotted
+      # three times; the third was round 3's own fix pass, on the two
+      # pages the first version of this gate did not read. Pure text,
+      # ~50 ms.
+      - name: Verify the documented gate lists (check_gate_lists.mjs)
+        run: node scripts/check_gate_lists.mjs
+      # A regex that backtracks exponentially does not fail a build, it
+      # stops one: the corpus passes until a page happens to contain the
+      # trigger, and then a render worker sits inside String.replace
+      # forever. VOID_TAGS_RE shipped that way for as long as no alt text
+      # contained a slash, and its first fix was still exponential on a
+      # subtler witness. Nothing else here can see it, because there is
+      # nothing to see until the content changes.
+      #
+      # Reads regex literals AND every `new RegExp(...)` the source
+      # decides the arguments of. That second half is not a refinement:
+      # assembling a pattern from shared string constants is ordinary
+      # JavaScript, and for as long as this read literals only it was
+      # also a way out of the gate. Six such regexes went into one gate
+      # unseen, one of them polynomial.
+      #
+      # Gates on exponential only -- about a fifth of the patterns here
+      # are polynomial, nearly all the ordinary `<tag[^>]*>` shape on
+      # bounded input, and a gate that fails on day one gets switched
+      # off. The self-test probes run inside the same pass, classification
+      # and folding both, so a green line here cannot be a gate that has
+      # stopped detecting. No browser, no built tree, a few seconds
+      # sharded across the runner's CPUs.
+      #
+      # recheck's native backend is an optional dependency resolved per
+      # platform; if it is missing the script says so and falls back to
+      # the pure-JS implementation, which is slower but reaches the same
+      # verdict on every probe.
+      - name: Verify regex safety (check_regex_safety.mjs)
+        run: node scripts/check_regex_safety.mjs
+      # render.mjs applies several kramdown-parity rewrites to RAW markdown,
+      # before anything has been parsed, so none of them can tell prose from
+      # code -- on a site whose subject matter is code. Four defects of that
+      # shape shipped: `{% raw %}` stripped inside fences, admonition bodies
+      # losing the indentation of the code they contain, `Items[1](a, b)`
+      # percent-encoded inside a fence, and a YAML sample's closing `---`
+      # deleted with the line above it promoted to a heading.
+      #
+      # No other gate can see any of it: the corruption is inside <code>,
+      # and the link, integrity, publish and axe checks all pass over it.
+      # Tokenise the source, apply the real rewrite chain, re-tokenise, and
+      # compare the literal regions. Probes ride along in the same run so a
+      # clean corpus cannot be mistaken for a working gate. No browser, no
+      # built tree.
+      - name: Verify code regions survive the pre-render rewrites (check_code_regions.mjs)
+        run: node scripts/check_code_regions.mjs
+      # The page-count drift guard reports nothing on a healthy tree, so a
+      # green build says exactly what a guard that had stopped working says.
+      # These probes make the other assertion, against a scratch baseline
+      # rather than the committed one. The first replays the defect that
+      # motivated it: 37 pages of AppGlobalClassObject lost to a blanket
+      # exclude rule, under a guard that knew only a floor of 836 against a
+      # real 908. No browser, no built tree.
+      - name: Verify the page-count drift guard (check_page_baseline.mjs)
+        run: node scripts/check_page_baseline.mjs
+      # Graphviz sizes each node box from a width table; the browser paints
+      # the label with a real font. Nothing in the build compares the two, so
+      # a mismatch ships as text hanging outside its box on a green build --
+      # which is how 27 labels across three diagrams went out, through a full
+      # accessibility sweep, unreported. axe does not evaluate SVG <text>
+      # geometry either.
+      #
+      # Safe on CI's font set: it loads Inter from the committed .woff2 by
+      # @font-face rather than relying on an installed face, so unlike the
+      # target-size rules it measures the same here as on a dev box.
+      - name: Verify DOT diagram fit (check_dot_fit.mjs)
+        run: node scripts/check_dot_fit.mjs
       # check_a11y.mjs injects a PATCHED axe bundle (plain-color-fields,
       # -26 % on a realistic page set -- see builder/PLAN-axe-perf.md), so the
       # patch has to be verified before its results are trusted. The patch
@@ -137,7 +220,7 @@ jobs:
       # PR that bumps axe-core is exactly when it earns its place.
       - name: Verify axe source patch (check_axe_patch_equiv.mjs)
         run: node scripts/check_axe_patch_equiv.mjs
-      # The scan is eleven pages of ~1,160, so its page list decides what it can
+      # The scan is thirteen pages of ~1,160, so its page list decides what it can
       # report at all. This fails when the site grows a markup construct no
       # sample page carries -- the drift that let the previous six-page sample
       # report a clean pass while 54 pages had violations in constructs it never

.github/workflows/tbdocs-gh-pages.yml

@@ -101,6 +101,70 @@ jobs:
       # comparison against the build's own checker.
       - name: Verify the standalone link checker (check_links_diff.mjs)
         run: node scripts/check_links_diff.mjs --case fixture --a script --b index
+      # The publish allowlist (builder/publish-policy.mjs) is enforced
+      # inside the build above, so a green build already says nothing
+      # unpublishable is in docs/. It does NOT say the allowlist still
+      # refuses anything: one widened until it refuses nothing reports the
+      # same clean pass. This asserts the refusals against named probes --
+      # a stray .bak, a .pem, a scratch .md with no frontmatter. No
+      # browser, no built tree, ~40 ms.
+      - name: Verify the publish allowlist (check_publish_policy.mjs)
+        run: node scripts/check_publish_policy.mjs
+      # The two gate lists on Tools.md against the wrappers that run
+      # them, plus every gate count stated in prose in README.md or
+      # under docs/Documentation/. Documented gate counts have rotted
+      # three times; the third was round 3's own fix pass, on the two
+      # pages the first version of this gate did not read. Pure text,
+      # ~50 ms.
+      - name: Verify the documented gate lists (check_gate_lists.mjs)
+        run: node scripts/check_gate_lists.mjs
+      # An exponentially backtracking regex does not fail a build, it
+      # stops one -- a render worker sits inside String.replace forever
+      # the first time a page contains the trigger. VOID_TAGS_RE shipped
+      # that way, and so did its first fix. See the same step in
+      # checks.yml for what it gates on and why only exponential.
+      #
+      # Here for the same reason check_dot_fit.mjs is: checks.yml runs
+      # only on pull requests, so this is the one gate a regex merged by
+      # a direct push to `staging` would otherwise never meet. No browser
+      # and no built tree, so its position relative to the build does not
+      # matter.
+      - name: Verify regex safety (check_regex_safety.mjs)
+        run: node scripts/check_regex_safety.mjs
+      # The pre-render rewrites in render.mjs run over raw markdown and
+      # cannot tell prose from code; four defects of that shape shipped,
+      # and nothing else looks inside <code>. See the same step in
+      # checks.yml. Here for the same reason the gate above is: checks.yml
+      # runs only on pull requests, so this is the one place a rewrite
+      # merged by a direct push to `staging` would meet it. No browser and
+      # no built tree.
+      - name: Verify code regions survive the pre-render rewrites (check_code_regions.mjs)
+        run: node scripts/check_code_regions.mjs
+      # The page-count drift guard reports nothing on a healthy tree, so a
+      # green build says exactly what a guard that had stopped working says.
+      # These probes make the other assertion, against a scratch baseline
+      # rather than the committed one. The first replays the defect that
+      # motivated it: 37 pages of AppGlobalClassObject lost to a blanket
+      # exclude rule, under a guard that knew only a floor of 836 against a
+      # real 908. No browser, no built tree.
+      - name: Verify the page-count drift guard (check_page_baseline.mjs)
+        run: node scripts/check_page_baseline.mjs
+      # Graphviz sizes each node box from a width table; the browser paints the
+      # label with a real font, and nothing in the build compares the two -- so a
+      # mismatch ships as text hanging outside its box on a green build. See the
+      # same step in checks.yml for how 27 labels once went out that way.
+      #
+      # checks.yml only runs on pull requests, so this is the one gate a diagram
+      # merged by a direct push to `staging` -- or by a manual dispatch -- would
+      # otherwise never meet.
+      #
+      # After the build on purpose: builder/dot.mjs rewrites a stale .svg from
+      # its .dot in place, so this measures the bytes about to be deployed, not
+      # the ones that were committed. Chromium is already installed above, and
+      # the check loads Inter from the committed .woff2 rather than an installed
+      # face, so it measures the same here as on a dev box. Five diagrams, ~1 s.
+      - name: Verify DOT diagram fit (check_dot_fit.mjs)
+        run: node scripts/check_dot_fit.mjs
       # check_a11y.mjs injects a PATCHED axe bundle; verify the patch is still
       # value-preserving before trusting what it reports. See the same step in
       # checks.yml for why the fingerprint gate does not cover this.

.gitignore

@@ -17,3 +17,9 @@ indexer/.packages/
 /test/fixtures/_out-offline/
 /test/fixtures/_out-pdf/
 /test/fixtures/_out.json
+
+
+# scripts/build_fonts.py caches the upstream font release archives here
+# (~190 MB). The subset .woff2 it produces ARE committed, under
+# docs/assets/fonts/ -- only the archives are throwaway.
+/.font-cache/

BOOKPLAN.md

@@ -1,5 +1,25 @@
 # PDF Book Build — Plan
 
+> **Historical design record. Do not follow the commands or file paths in it.**
+>
+> This is the staged plan, written in the Jekyll era, for turning the PDF from a flat concatenation of every reference page into an actual book. The structure it designs — front matter, numbered parts, chapter dividers, in-PDF cross-references — is what the book has today; the file is kept for the reasoning behind each decision, not as instructions. Page counts, timings and command lines quoted below are from that era.
+>
+> **The build system it describes no longer exists.** The Phase 10 cutover replaced Jekyll with `tbdocs`, the Node.js generator under [builder/](builder/), and `docs/_plugins/`, `docs/_includes/` and `docs/_layouts/` were deleted — so every Ruby plugin, include and layout named below survives only in git history. Concretely:
+>
+> | Named below | Now |
+> |---|---|
+> | `bundle exec jekyll build` | `build.bat` — `node builder/tbdocs.mjs --src docs` |
+> | `npx pagedjs-cli … -o _pdf/book.pdf` | `book.bat` — `node book/render-book.mjs … -o "docs/_pdf/twinBASIC Book.pdf"` |
+> | `docs/book.bat` | [`book.bat`](book.bat), at the repository root |
+> | `docs/_data/book.yml` | [`docs/_book.yml`](docs/_book.yml) |
+> | `_plugins/pdfify.rb` | [`builder/pdf.mjs`](builder/pdf.mjs), pipeline Phase 8 |
+> | `_plugins/book-*.rb`, `_includes/book-chapter-body.html`, `_layouts/book-combined.html` | [`builder/book.mjs`](builder/book.mjs) |
+> | `assets/css/rouge.css` | `assets/css/tb-highlight.css`, generated by `builder/highlight-theme.mjs` |
+>
+> One entry under [Rendering gotchas](#build-environment) has stopped applying and is the one most likely to be acted on: **"PowerShell cannot invoke `npx` directly" no longer affects `book.bat`.** That batch file calls `node`, not `npx`, and a `.bat` is interpreted by `cmd.exe` whichever shell launches it — so no `.ps1` shim is reached and the execution policy is never consulted. The paged.js and CSS Paged Media gotchas above it still hold; the forked bundle lives at `book/lib/paged.browser.js`.
+>
+> **Current documentation.** The two-stage pipeline, the renderer's flags and phases, and how to triage a failed render are on the site: [PDF Generation](docs/Documentation/PDF-Generation.md) and [Book Configuration](docs/Documentation/Book-Configuration.md), with the vendored-library patches in [Fixes-PagedJS.md](docs/Documentation/Fixes-PagedJS.md) and [Fixes-PDFLib.md](docs/Documentation/Fixes-PDFLib.md). The Phase 8 specification is [builder/PLAN-8.md](builder/PLAN-8.md), and the Jekyll era as a whole is recorded in [WIP.OldJekyll.md](WIP.OldJekyll.md).
+
 Currently `book.bat` produces a ~1500-page PDF that is a flat concatenation of every reference page. It works, but it doesn't read like a book — no front matter, no parts, no global TOC, every chapter is `<h1>`, and "See Also" cross-references point at standalone `file://` URLs rather than jumping within the PDF.
 
 This file is the staged plan for turning that output into an actual book. Phases are independent; each one ends in a verifiable rendered artefact and is a reasonable commit boundary.

README.md

@@ -24,6 +24,29 @@ If you want to get involved in improving this documentation directly, please for
 
 All help is *very much* appreciated :)
 
+## Building the site
+
+The site is rendered by `tbdocs`, a Node.js static site generator kept in [`builder/`](builder/). You need **Node.js 22+**; a PDF or accessibility run additionally needs Chromium, installed once with `npx puppeteer browsers install chrome` (add `--install-deps` on Linux only).
+
+```
+npm ci        # once, from the repository root
+build.bat     # renders _site/, _site-offline/ and _site-pdf/, and link-checks them
+serve.bat     # localhost:4000 with watch + live reload
+check.bat     # the gates that read the built site, ending in the accessibility scan
+test.bat      # the gates that test the toolchain itself
+book.bat      # renders the PDF book; run build.bat first
+```
+
+A clean `build.bat && check.bat` is the bar for "ready to commit"; add `test.bat` when the change touched anything outside `docs/`. Each wrapper names the gates it runs, in order, on [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools). On Linux or macOS, run the `node` command inside each batch file directly --- they are thin wrappers.
+
+Where to read more:
+
+- **Writing or editing a page** --- [Authoring Pages](https://docs.twinbasic.com/Documentation/Development/Authoring) covers frontmatter, headings, prose style, attribution and links.
+- **The build and deployment workflow** --- [Building and Deployment](https://docs.twinbasic.com/Documentation/Development/Building).
+- **Every command and flag** --- [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools).
+- **Changing the generator itself** --- [tbdocs Internals](https://docs.twinbasic.com/Documentation/Development/Builder), with [`builder/README.md`](builder/README.md) next to the code.
+- **Adding a build task or a markdown-it plugin** --- [Extending the Builder](https://docs.twinbasic.com/Documentation/Development/Extending) covers all four extension points --- a task in the build graph, a markdown-it plugin, a render-worker sub-stage, and a verification gate in `check.bat` or `test.bat`.
+