Add discoverability, dark mode, search, social cards, banner grammar, and learner analytics

[adewale]

What

Ships the distribution and product-polish pass from the project-elevation review: SEO plumbing (sitemap, JSON-LD, robots.txt), dark mode + skip link, client-side example search, per-example social-card images, the banner position grammar from docs/visual-explainer-spec.md (with curated multi-figure pairs), full journey coverage of all 109 examples, and a learner-behavior report over the existing observability events.

Why

The project's internal quality machine is saturated (per docs/rubric-saturation.md) while its outward distribution surface was nearly empty: no sitemap, no structured data, no search, no dark mode, no social-card images, and no view of what learners actually do. This PR converts existing investments (the marginalia figure set, the wide-event observability, the quality registries) into visitor-facing and author-facing value. The banner grammar was already specced and prototyped (/prototyping/layout-banner-*) but never rolled out.

How

• SEO: a /sitemap.xml route in app.py, public/robots.txt with a Sitemap directive, and JSON-LD (WebSite on home, TechArticle/LearningResource on examples) injected through a new _layout parameter. scripts/lint_seo_cache.py now enforces all of it.
• Dark mode: a prefers-color-scheme: dark block overriding the existing CSS custom properties. Shiki moves to dual themes (CSS-variable swap); CodeMirror picks oneDarkHighlightStyle via matchMedia. Marginalia figures render on a light "paper" chip in dark mode, so the locked SVG grammar is untouched.
• Search: scripts/build_search_index.py emits a JSON index (title/section/summary/notes text, lowercased at build time) that goes through the existing fingerprint pipeline; public/search.js is a dependency-free ranked matcher with a / shortcut and keyboard navigation. Chosen over a search library to keep the zero-dependency asset story.
• Social cards: scripts/build_social_cards.py composes a 1200×630 HTML card per example around its curated marginalia figure; scripts/build_social_cards.mjs rasterizes all 110 through one headless-Chrome CDP session to public/og/<slug>.jpg (JPEG q90 — 7.2 MB total vs 17 MB PNG). Pages reference them via og:image/twitter:card.
• Banner grammar: render_banner(slug, position) implements before / after-cell-N (legacy anchor cell-N) / after-walkthrough, with multiple figures per position rendering as one small-multiple banner. ATTACHMENTS stays the single registry — extending its anchor vocabulary (instead of the spec's proposed parallel BANNERS dict) keeps all five contract families intact. Curated pairs: mutability (aliasing vs frozen tuple), positional-only-parameters (/ and * twins), metaclasses (both triangles), tuples (frozen tuple vs growing list), plus the one-pass caret on iterator-vs-iterable's exhaustion cell.
• Journeys: the five previously unreferenced examples joined their natural sections with outcome-registry support updates; stale "gap placeholder" meta copy removed.
• Learner analytics: scripts/learner_report.py consumes exported wide events (auto-detects raw payload, wrangler tail, and Workers Logs envelopes) and reports most-read pages, most-run examples with edited/error shares and execution percentiles, journey traffic, and /examples/ 404s. Documented in docs/learner-analytics.md.

Testing

• 26 new tests across tests/test_app.py (Discoverability, DarkModeAndAccessibility, Search, SocialCard, Banner suites) and tests/test_learner_report.py; the geometry anchor contract now accepts the position grammar.

• scripts/check_search_ranking.mjs (new make search-ranking-test, wired into make verify) exercises ranking against the real generated index.

• Full suite: 120 tests pass, plus SEO/cache lint, example verifier (100% golden parity), all nine quality checks, formatter, and ruff.

• New assertions fail without the features (e.g. removing a pair figure fails BannerTests; removing JSON-LD fails the linter and DiscoverabilityTests).

• Not run locally: make browser-layout-test needs a local Worker and the dev container's network policy blocks the Pyodide download — it runs in this repo's CI verify workflow.

• Manual: rendered pages screenshotted via headless Chromium — dark-mode example page, home with search results open, the mutability/positional-only pair banners, and sample social cards.

• New/modified tests pass

• Tests fail when the change is reverted (regression guard)

• Full test suite passes (no regressions)

• Manual testing completed (described above)

Screenshots / Recordings

Visual changes: dark palette, search box + results dropdown on home, pair banners between cells, and the social cards. To reproduce locally:

• Pages: uv run --group workers pywrangler dev --port 9696, then visit /, /examples/mutability, /examples/positional-only-parameters (toggle OS dark mode for the palette).
• Social cards: make social-cards regenerates public/og/*.jpg (set CHROME_PATH if Chrome isn't at the default location); the committed files render at /og/<slug>.jpg.
• The banner layout was validated against the pre-existing prototypes at /prototyping/layout-banner-{single,pair,trio}.html.

Risk

• The layout template and _layout signature changed, so every page re-renders — the HTML cache version rolls on deploy (intentional, existing mechanism) and the CDN re-fills.
• The walkthrough renderer changed from a per-cell loop to _render_walkthrough; pages without banners render byte-identically (covered by the existing rendering-contract tests).
• 7.2 MB of committed JPEGs in public/og/ — deliberately excluded from make check-generated because rasterized bytes vary across Chrome versions; the SEO linter checks existence instead, so a new example without a card fails verification.
• editor.js/syntax-highlight.js changed (fingerprints roll); the CodeMirror one-dark import adds one esm.sh module fetched only by the editor page.
• No example source (src/example_sources/*.md) content changed; golden parity is at 100%.

https://claude.ai/code/session_012tBECRGRPmM2dj5b3FFJGo