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

Distribution and product-polish pass:

- /sitemap.xml route + robots.txt Sitemap directive; JSON-LD structured
  data (WebSite on home, TechArticle/LearningResource on examples),
  enforced by the SEO linter.
- Dark mode via prefers-color-scheme: inverted warm palette, dual-theme
  Shiki, dark CodeMirror highlight style, marginalia figures on a light
  paper chip so the locked grammar stays untouched. Skip-to-content
  link on every page.
- Client-side example search on the home page: build-step JSON index,
  fingerprinted search.js/search-index.json assets, "/" shortcut, Node
  ranking check wired into make verify.
- Per-example social cards composed from each example's marginalia
  figure, rasterized with headless Chrome to public/og/<slug>.jpg and
  referenced via og:image/twitter:card (make social-cards).
- Learner-behavior report aggregating exported Worker wide events into
  most-read pages, most-run examples (edited/error shares, execution
  percentiles), journey traffic, and missing-example 404s.
- Journeys now cover all 109 examples: five previously unreferenced
  examples joined their natural sections with outcome-registry support
  updates; stale "gap placeholder" copy removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012tBECRGRPmM2dj5b3FFJGo

Author: claude

.gitignore

@@ -9,3 +9,6 @@ dist/
 
 python_modules/
 .venv-workers/
+
+# Social-card HTML intermediates (rasterized output lives in public/og/)
+build/

CHANGELOG.md

@@ -1,22 +1,32 @@
-.PHONY: test embed-examples build check-generated fingerprint browser-layout-test seo-cache-lint verify-examples check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported score-example-criteria check-quality-scores check-no-figure-rationales check-journey-outcomes quality-checks rubric-audit format-examples verify-python-version verify smoke-deployment dev deploy lint
+.PHONY: test embed-examples build-search-index build check-generated fingerprint browser-layout-test search-ranking-test social-cards seo-cache-lint verify-examples check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported score-example-criteria check-quality-scores check-no-figure-rationales check-journey-outcomes quality-checks rubric-audit format-examples verify-python-version verify smoke-deployment dev deploy lint
 
 test:
 	uv run --python 3.13 python -m unittest discover -s tests -v
 
 embed-examples:
 	scripts/embed_example_sources.py
 
-build: embed-examples fingerprint
+build-search-index: embed-examples
+	uv run --python 3.13 scripts/build_search_index.py
+
+build: embed-examples build-search-index fingerprint
 
 check-generated: build
-	git diff --exit-code src/example_sources_data.py src/asset_manifest.py public/_headers
+	git diff --exit-code src/example_sources_data.py src/asset_manifest.py public/_headers public/search-index.json
 
-fingerprint: embed-examples
+fingerprint: embed-examples build-search-index
 	scripts/fingerprint_assets.py
 
 browser-layout-test:
 	scripts/check_browser_layout.mjs
 
+search-ranking-test:
+	scripts/check_search_ranking.mjs
+
+social-cards:
+	uv run --python 3.13 scripts/build_social_cards.py
+	scripts/build_social_cards.mjs
+
 seo-cache-lint:
 	scripts/lint_seo_cache.py
 
@@ -64,7 +74,7 @@ verify-python-version: build
 lint:
 	uv run ruff check src tests scripts
 
-verify: build test seo-cache-lint verify-examples quality-checks browser-layout-test lint check-generated
+verify: build test seo-cache-lint verify-examples quality-checks browser-layout-test search-ranking-test lint check-generated
 
 dev:
 	uv run pywrangler dev --port 9696

Makefile

@@ -316,6 +316,7 @@ journey = "iteration"
 section = "See the protocol behind `for`."
 support = [
   "iterating-over-iterables",
+  "iterator-vs-iterable",
   "iterators",
   "generators",
 ]
@@ -434,12 +435,14 @@ support = [
   "inheritance-and-super",
   "dataclasses",
   "properties",
+  "classmethods-and-staticmethods",
   "special-methods",
   "truth-and-size",
   "container-protocols",
   "callable-objects",
   "operator-overloading",
   "attribute-access",
+  "bound-and-unbound-methods",
   "descriptors",
   "metaclasses",
 ]
@@ -456,6 +459,7 @@ section = "Keep runtime and static analysis separate."
 support = [
   "type-hints",
   "protocols",
+  "abstract-base-classes",
   "enums",
   "runtime-type-checks",
 ]
@@ -473,6 +477,7 @@ support = [
   "union-and-optional-types",
   "type-aliases",
   "typed-dicts",
+  "structured-data-shapes",
   "literal-and-final",
   "callable-types",
 ]

README.md

@@ -7,8 +7,17 @@
 /editor.*.js
   Cache-Control: public, max-age=31536000, immutable
 
+/search.*.js
+  Cache-Control: public, max-age=31536000, immutable
+
+/search-index.*.json
+  Cache-Control: public, max-age=31536000, immutable
+
 /favicon.svg
   Cache-Control: public, max-age=31536000, immutable
 
+/og/*
+  Cache-Control: public, max-age=86400
+
 /prototyping/*
   Cache-Control: no-cache, must-revalidate

docs/learner-analytics.md

@@ -2,6 +2,10 @@ import { EditorState } from 'https://esm.sh/@codemirror/state@6.5.2';
 import { EditorView, lineNumbers } from 'https://esm.sh/@codemirror/view@6.41.1?deps=@codemirror/state@6.5.2';
 import { defaultHighlightStyle, syntaxHighlighting } from 'https://esm.sh/@codemirror/language@6.12.3?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1';
 import { python } from 'https://esm.sh/@codemirror/lang-python@6.2.1?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1,@codemirror/language@6.12.3';
+import { oneDarkHighlightStyle } from 'https://esm.sh/@codemirror/theme-one-dark@6.1.3?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1,@codemirror/language@6.12.3';
+
+const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+const highlightStyle = prefersDark ? oneDarkHighlightStyle : defaultHighlightStyle;
 
 const textarea = document.getElementById('code-editor');
 const form = document.querySelector('form.runner-editor');
@@ -14,7 +18,7 @@ if (textarea && form) {
       doc: textarea.value,
       extensions: [
         python(),
-        syntaxHighlighting(defaultHighlightStyle),
+        syntaxHighlighting(highlightStyle),
         lineNumbers(),
         EditorView.lineWrapping,
         EditorView.updateListener.of((update) => {

docs/quality-registries.toml

@@ -2,6 +2,10 @@ import { EditorState } from 'https://esm.sh/@codemirror/state@6.5.2';
 import { EditorView, lineNumbers } from 'https://esm.sh/@codemirror/view@6.41.1?deps=@codemirror/state@6.5.2';
 import { defaultHighlightStyle, syntaxHighlighting } from 'https://esm.sh/@codemirror/language@6.12.3?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1';
 import { python } from 'https://esm.sh/@codemirror/lang-python@6.2.1?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1,@codemirror/language@6.12.3';
+import { oneDarkHighlightStyle } from 'https://esm.sh/@codemirror/theme-one-dark@6.1.3?deps=@codemirror/state@6.5.2,@codemirror/view@6.41.1,@codemirror/language@6.12.3';
+
+const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+const highlightStyle = prefersDark ? oneDarkHighlightStyle : defaultHighlightStyle;
 
 const textarea = document.getElementById('code-editor');
 const form = document.querySelector('form.runner-editor');
@@ -14,7 +18,7 @@ if (textarea && form) {
       doc: textarea.value,
       extensions: [
         python(),
-        syntaxHighlighting(defaultHighlightStyle),
+        syntaxHighlighting(highlightStyle),
         lineNumbers(),
         EditorView.lineWrapping,
         EditorView.updateListener.of((update) => {