feat(site): search the explainer and the docs (phase 6)

[TMHSDigital]

Stacked on #68: its base is site/phase-5-shell, so the diff shows only this phase. It retargets to main when #68 merges.

The site has eight docs and a long explainer, but the only way to find something was the browser's find-in-page on one page at a time. This adds site-wide search with no library and no third-party request.

What a reader gets

• Open search from the header's Search button, or with / or Ctrl+K.
• Results show page › heading with a snippet that marks the matched terms.
• Arrow keys move, Enter opens, Esc closes and returns focus. A search that finds nothing says so.

How it works

• build_site.py writes search-index.json: one entry per section of every doc and of the explainer, 90 entries and about 106 KB.
  • It is built from the per-section text the renderer started returning in phase 5.
  • The browser fetches it from the site only when search first opens.
• site/search.js does the ranking with pure functions, UMD like floor.js:
  • every term must match the start of a word, ignoring case and accents;
  • a match in a heading counts 3 and a match in the page name 2;
  • body matches count 1 each, capped at 5 per term;
  • ties keep site order, so a page's own entry leads its sections.
• The dialog is built by site.js, so a reader without scripts never sees a dead control.
• Snippets are assembled with textContent and <mark> nodes, never innerHTML.
• Fix found while testing: section text used to run words together across a markdown line break ("Temperaturescaling"). The renderer now keeps the space, with a self-test case.

CI

scripts/check_search.mjs is standard-library Node, and site.yml now runs it. It checks:

• 12 ranking and snippet cases;
• that every index entry names a page and an id that exist in the built site;
• that the files the page scripts fetch or load (the worker, the example run, the index) exist. check_site_links.mjs only follows HTML tags, so it cannot see these. This covers part of CI checks do not cover everything that ships #54.

Checked

• ruff, mypy --strict, and pytest pass. Three new tests cover the index: its shape and order, refusing an explainer it cannot read, and the per-entry length cap.
• render_docs --self-test passes 21 cases. check_search.mjs and check_site_links.mjs pass on the built site.
• In the browser (Playwright): / and Ctrl+K open search, Enter follows the top result, Esc closes and focus returns to the button that opened it. The phone width fits, and the console shows no errors.

Found while testing: a link to /#planner stops short of the planner, because the worked example renders after load and pushes it down. That happens on the live site today. Phase 7 fixes it, since it rewrites that script.

🤖 Generated with Claude Code