Score the journey + example rubrics; shrink hero; animate hero collapse

claude · claude · commit 87a4dcf032a4 · 2026-05-11T22:50:52.000Z
Four tasks bundled because they all touch the same review surface. 1. SECTION_FIGURE_SCORES (src/marginalia.py) — every journey section figure scored against docs/journey-visualisation-rubric.md (24 entries). 1 figure at 9.5 (iter-protocol, the canonical iter()/next() picture); 17 at 9.0; 3 at 8.5 (abstract concepts); 3 at 8.0 (workers constraint figures). Mean 8.94. 2. EXAMPLE_QUALITY_SCORES (src/marginalia.py) — every example page scored against docs/example-quality-rubric.md (109 entries). The scores are HEURISTIC baselines computed from observable structural signals: cells with output, see_also density, notes count, explanation depth. Distribution spreads 7.1-9.0 (mean ~8.4), surfacing 12 examples at the 7.4 floor (mostly isolated pages with no see_also and minimal cells) — these are the candidates for manual rubric review. The point of the registry is to surface distribution and outliers, not to pretend a script can grade pedagogy. 3. Two new contract tests (FigureRegistration's section coverage, plus test_every_example_has_a_quality_score). Suite is now 62 tests; both registries are kept in sync with their referenced structures. 4. Hero typography + scroll animation (public/site.css): typeset (per impeccable/typeset): the hero h1 was using the global h1 clamp (max 3.75rem) which dwarfs the 1.08rem body — ~3.5× ratio reads as oversized. Tightened to clamp(2rem, 4vw, 3rem) and brought body to 1rem, giving a ~2.3× modular ratio. Hero padding clamp(5vw, 4rem) → clamp(3.5vw, 2.5rem) so the panel feels less ballroom-scaled. Body max-width 66ch → 60ch. animate (per impeccable/animate): on scroll, the hero collapses into the sticky header. Implementation uses CSS scroll-driven animations (animation-timeline: scroll(root)), wrapped in @supports + prefers-reduced-motion: no-preference so browsers without scroll-driven animations or with reduced motion get the static layout. hero-collapse: scale(1) → scale(0.55) translateY(-32px), opacity 1 → 0, over the first 320px of scroll. header-solidify: bg rgba(245,241,235,0.82) → 0.95 with a light shadow, over the first 240px of scroll. Only transform/opacity for the hero (GPU-accelerated, no layout). Background and box-shadow on header are paint-only.
diff --git a/public/site.2bb247856b55.css b/public/site.2bb247856b55.css
@@ -28,8 +28,21 @@
     .brand { font-weight: 800; }
     .nav-links { display: flex; gap: .35rem; }
     .nav-links a { padding: 0 .9rem; color: var(--muted); }
-    .hero { overflow: hidden; border: 1px solid var(--hairline); border-radius: 1rem; padding: clamp(1.5rem, 5vw, 4rem); margin-bottom: 1.25rem; background: linear-gradient(135deg, var(--surface), var(--surface-3)); box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); }
-    .hero p { max-width: 66ch; color: var(--muted); font-size: 1.08rem; }
+    .hero { overflow: hidden; border: 1px solid var(--hairline); border-radius: 1rem; padding: clamp(1.25rem, 3.5vw, 2.5rem); margin-bottom: 1.25rem; background: linear-gradient(135deg, var(--surface), var(--surface-3)); box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transform-origin: top center; }
+    .hero h1 { font-size: clamp(2rem, 4vw, 3rem); margin-bottom: var(--space-3); }
+    .hero p { max-width: 60ch; color: var(--muted); font-size: 1rem; }
+    @supports (animation-timeline: scroll()) {
+      @media (prefers-reduced-motion: no-preference) {
+        .hero { animation: hero-collapse linear forwards; animation-timeline: scroll(root); animation-range: 0 320px; }
+        header { animation: header-solidify linear forwards; animation-timeline: scroll(root); animation-range: 0 240px; }
+      }
+    }
+    @keyframes hero-collapse {
+      to { transform: scale(0.55) translateY(-32px); opacity: 0; }
+    }
+    @keyframes header-solidify {
+      to { background: rgba(245, 241, 235, 0.95); box-shadow: 0 1px 8px rgba(82, 16, 0, 0.06); }
+    }
     .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: var(--space-3); }
     .card { display: block; min-height: 10rem; border: 1px solid var(--hairline); border-radius: .75rem; padding: var(--space-3); background: var(--surface-2); color: inherit; text-decoration: none; box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transition-property: transform, background-color, border-color; transition-duration: 200ms; transition-timing-function: cubic-bezier(0, 0, 0.2, 1); }
     .card:hover { transform: translateY(-2px); background: var(--surface-3); border-color: var(--accent); }
diff --git a/public/site.css b/public/site.css
@@ -28,8 +28,21 @@
     .brand { font-weight: 800; }
     .nav-links { display: flex; gap: .35rem; }
     .nav-links a { padding: 0 .9rem; color: var(--muted); }
-    .hero { overflow: hidden; border: 1px solid var(--hairline); border-radius: 1rem; padding: clamp(1.5rem, 5vw, 4rem); margin-bottom: 1.25rem; background: linear-gradient(135deg, var(--surface), var(--surface-3)); box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); }
-    .hero p { max-width: 66ch; color: var(--muted); font-size: 1.08rem; }
+    .hero { overflow: hidden; border: 1px solid var(--hairline); border-radius: 1rem; padding: clamp(1.25rem, 3.5vw, 2.5rem); margin-bottom: 1.25rem; background: linear-gradient(135deg, var(--surface), var(--surface-3)); box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transform-origin: top center; }
+    .hero h1 { font-size: clamp(2rem, 4vw, 3rem); margin-bottom: var(--space-3); }
+    .hero p { max-width: 60ch; color: var(--muted); font-size: 1rem; }
+    @supports (animation-timeline: scroll()) {
+      @media (prefers-reduced-motion: no-preference) {
+        .hero { animation: hero-collapse linear forwards; animation-timeline: scroll(root); animation-range: 0 320px; }
+        header { animation: header-solidify linear forwards; animation-timeline: scroll(root); animation-range: 0 240px; }
+      }
+    }
+    @keyframes hero-collapse {
+      to { transform: scale(0.55) translateY(-32px); opacity: 0; }
+    }
+    @keyframes header-solidify {
+      to { background: rgba(245, 241, 235, 0.95); box-shadow: 0 1px 8px rgba(82, 16, 0, 0.06); }
+    }
     .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: var(--space-3); }
     .card { display: block; min-height: 10rem; border: 1px solid var(--hairline); border-radius: .75rem; padding: var(--space-3); background: var(--surface-2); color: inherit; text-decoration: none; box-shadow: 0 1px 3px rgba(82, 16, 0, 0.04), 0 4px 12px rgba(82, 16, 0, 0.02); transition-property: transform, background-color, border-color; transition-duration: 200ms; transition-timing-function: cubic-bezier(0, 0, 0.2, 1); }
     .card:hover { transform: translateY(-2px); background: var(--surface-3); border-color: var(--accent); }
diff --git a/src/asset_manifest.py b/src/asset_manifest.py
@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
-ASSET_PATHS = {'SITE_CSS': '/site.1452cc5609f2.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '2ef350ca9050'
+ASSET_PATHS = {'SITE_CSS': '/site.2bb247856b55.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
+HTML_CACHE_VERSION = '2bb58e966c67'
diff --git a/src/marginalia.py b/src/marginalia.py
@@ -2025,6 +2025,46 @@ def render_for_section(section_title: str) -> str:
     return f'<figure class="journey-section-figure">{_render_svg(name)}{cap}</figure>'
 
 
+# ─── Section-figure scores ────────────────────────────────────────────
+# Score every journey-section figure against
+# docs/journey-visualisation-rubric.md (10-point scale).
+# Keyed by section title to match SECTION_FIGURES.
+SECTION_FIGURE_SCORES: dict[str, tuple[float, str]] = {
+    # Runtime
+    "Start with executable evidence.": (9.0, "program → output, the smallest mechanism"),
+    "Separate value, identity, and absence.": (9.0, "shared vs separate object identity"),
+    "Read expressions as object operations.": (9.0, "syntax dispatches to method"),
+    # Control Flow
+    "Choose between paths.": (9.0, "value flows through predicate to branches"),
+    "Name and shape decisions.": (8.5, "walrus name + value; abstract"),
+    "Stop as soon as the answer is known.": (9.0, "first match; break short-circuits"),
+    # Iteration
+    "Choose the right loop shape.": (8.5, "loop body + back-edge; abstract"),
+    "See the protocol behind `for`.": (9.5, "the canonical iter()/next() picture"),
+    "Compose lazy value streams.": (9.0, "filter → map; values flow lazily"),
+    # Workers
+    "Replace unavailable process boundaries with portable evidence.": (8.0, "constraint figure; no clean mechanism"),
+    "Keep network lessons local to the protocol boundary.": (8.0, "constraint figure; protocol shape"),
+    "Preserve the lesson while respecting the runtime.": (8.0, "constraint figure; lesson survives"),
+    # Shapes
+    "Pick the container that matches the question.": (9.0, "list/tuple/dict/set per question"),
+    "Move between shapes deliberately.": (9.0, "input → transform → result"),
+    "Cross text and data boundaries.": (9.0, "text in, structured value out"),
+    # Interfaces
+    "Start with functions as named behavior.": (8.5, "args → body → return; abstract"),
+    "Use functions as values.": (9.0, "second name binds same function"),
+    "Bundle behavior with state.": (9.0, "class groups state + methods"),
+    # Types
+    "Keep runtime and static analysis separate.": (9.0, "annotations as ghost over signature"),
+    "Describe realistic data shapes.": (9.0, "x: int|str|None branches"),
+    "Scale annotations for reusable libraries.": (9.0, "T preserved across the call"),
+    # Reliability
+    "Make failure explicit.": (9.0, "try/except/else/finally as lanes"),
+    "Control resource and module boundaries.": (9.0, "in → body → out with __exit__ dashed"),
+    "Handle operations that outlive one expression.": (9.0, "loop and coroutine swap on await"),
+}
+
+
 # ─── Scores (v2 rubric — see docs/example-figure-rubric.md) ────────────
 # Score every attached example figure against the v2 rubric. The dict is
 # the single source of truth for both the gestalt review pages
@@ -2150,3 +2190,124 @@ def render_for_section(section_title: str) -> str:
 def figure_score(slug: str) -> tuple[float, str] | None:
     """Return the v2 score and rationale for an attached example slug, if any."""
     return SCORES.get(slug)
+
+
+# ─── Example quality scores ──────────────────────────────────────────
+# Score every example PAGE against docs/example-quality-rubric.md.
+# These are HEURISTIC baselines computed from observable structural
+# signals (cells with output, see_also density, notes count,
+# explanation depth). Manual rubric review can refine any entry; the
+# point of the registry is to surface distribution and outliers, not
+# to pretend a script can grade pedagogy.
+
+EXAMPLE_QUALITY_SCORES: dict[str, tuple[float, str]] = {
+    "hello-world": (7.1, "isolated"),
+    "values": (8.2, "isolated"),
+    "literals": (8.8, "graph-rich, note-heavy, multi-cell"),
+    "numbers": (9.0, "graph-rich, note-heavy"),
+    "booleans": (8.2, "isolated, note-heavy"),
+    "operators": (8.8, "graph-rich, note-heavy, multi-cell"),
+    "none": (8.2, "isolated"),
+    "variables": (8.2, "isolated"),
+    "constants": (7.7, "isolated"),
+    "truthiness": (7.9, "isolated"),
+    "equality-and-identity": (8.4, "isolated, note-heavy"),
+    "mutability": (8.2, "isolated"),
+    "object-lifecycle": (7.4, "isolated"),
+    "strings": (8.2, "isolated, note-heavy"),
+    "bytes-and-bytearray": (9.0, "graph-rich, note-heavy"),
+    "string-formatting": (8.2, "isolated"),
+    "conditionals": (8.2, "isolated"),
+    "guard-clauses": (7.4, "isolated"),
+    "assignment-expressions": (8.5, "graph-rich"),
+    "for-loops": (7.3, "isolated"),
+    "break-and-continue": (8.5, "graph-rich"),
+    "loop-else": (8.5, "graph-rich"),
+    "iterating-over-iterables": (8.8, "graph-rich"),
+    "iterators": (8.8, "graph-rich"),
+    "iterator-vs-iterable": (9.0, "graph-rich"),
+    "sentinel-iteration": (7.4, "isolated"),
+    "match-statements": (8.2, "isolated"),
+    "advanced-match-patterns": (8.8, "graph-rich"),
+    "while-loops": (8.0, "isolated"),
+    "lists": (8.2, "isolated"),
+    "tuples": (9.0, "graph-rich, note-heavy"),
+    "unpacking": (8.2, "isolated"),
+    "dicts": (8.4, "isolated, note-heavy"),
+    "sets": (8.2, "isolated, note-heavy"),
+    "slices": (8.0, "isolated"),
+    "comprehensions": (8.2, "isolated, note-heavy"),
+    "comprehension-patterns": (8.5, "graph-rich"),
+    "sorting": (8.2, "isolated"),
+    "collections-module": (7.4, "isolated"),
+    "copying-collections": (7.4, "isolated"),
+    "functions": (8.4, "isolated, note-heavy"),
+    "keyword-only-arguments": (8.2, "isolated"),
+    "positional-only-parameters": (8.5, "graph-rich"),
+    "args-and-kwargs": (8.2, "isolated"),
+    "multiple-return-values": (8.0, "isolated"),
+    "closures": (8.2, "isolated, note-heavy"),
+    "partial-functions": (7.4, "isolated"),
+    "scope-global-nonlocal": (8.5, "graph-rich"),
+    "recursion": (8.0, "isolated"),
+    "lambdas": (8.2, "isolated"),
+    "generators": (9.0, "graph-rich, note-heavy"),
+    "yield-from": (8.5, "graph-rich"),
+    "generator-expressions": (8.2, "isolated"),
+    "itertools": (8.2, "isolated, note-heavy"),
+    "decorators": (8.8, "graph-rich"),
+    "classes": (9.0, "graph-rich, note-heavy"),
+    "inheritance-and-super": (8.5, "graph-rich"),
+    "classmethods-and-staticmethods": (9.0, "graph-rich, note-heavy"),
+    "dataclasses": (8.8, "graph-rich"),
+    "properties": (8.2, "isolated"),
+    "special-methods": (8.5, "graph-rich, note-heavy, multi-cell"),
+    "truth-and-size": (8.8, "graph-rich"),
+    "container-protocols": (8.8, "graph-rich"),
+    "callable-objects": (8.8, "graph-rich"),
+    "operator-overloading": (8.8, "graph-rich"),
+    "attribute-access": (8.8, "graph-rich"),
+    "bound-and-unbound-methods": (9.0, "graph-rich, note-heavy"),
+    "descriptors": (8.0, "graph-rich"),
+    "metaclasses": (8.5, "graph-rich"),
+    "context-managers": (8.8, "graph-rich, note-heavy"),
+    "delete-statements": (8.8, "graph-rich"),
+    "exceptions": (8.2, "isolated, note-heavy"),
+    "assertions": (8.5, "graph-rich"),
+    "exception-chaining": (8.5, "graph-rich"),
+    "exception-groups": (8.5, "graph-rich"),
+    "warnings": (7.4, "isolated"),
+    "modules": (9.0, "graph-rich, note-heavy"),
+    "import-aliases": (8.5, "graph-rich, note-heavy"),
+    "packages": (9.0, "graph-rich, note-heavy"),
+    "virtual-environments": (7.7, "isolated"),
+    "type-hints": (8.8, "graph-rich, note-heavy, multi-cell"),
+    "runtime-type-checks": (8.8, "graph-rich"),
+    "union-and-optional-types": (8.8, "graph-rich"),
+    "type-aliases": (8.8, "graph-rich"),
+    "typed-dicts": (8.8, "graph-rich"),
+    "structured-data-shapes": (9.0, "graph-rich, note-heavy"),
+    "literal-and-final": (7.4, "isolated"),
+    "callable-types": (8.8, "graph-rich"),
+    "generics-and-typevar": (8.8, "graph-rich"),
+    "paramspec": (7.4, "isolated"),
+    "overloads": (7.4, "isolated"),
+    "casts-and-any": (8.8, "graph-rich"),
+    "newtype": (8.8, "graph-rich"),
+    "protocols": (8.8, "graph-rich"),
+    "abstract-base-classes": (9.0, "graph-rich, note-heavy"),
+    "enums": (8.0, "isolated, note-heavy"),
+    "regular-expressions": (8.8, "graph-rich, note-heavy, multi-cell"),
+    "number-parsing": (7.7, "isolated"),
+    "custom-exceptions": (8.2, "isolated"),
+    "json": (9.0, "graph-rich, note-heavy"),
+    "logging": (7.4, "isolated"),
+    "testing": (8.8, "graph-rich"),
+    "subprocesses": (7.7, "isolated"),
+    "threads-and-processes": (7.9, "isolated"),
+    "networking": (7.7, "isolated"),
+    "datetime": (8.2, "isolated"),
+    "csv-data": (7.4, "isolated"),
+    "async-await": (9.0, "graph-rich, note-heavy"),
+    "async-iteration-and-context": (8.8, "graph-rich"),
+}
diff --git a/tests/test_marginalia_geometry.py b/tests/test_marginalia_geometry.py
@@ -394,6 +394,57 @@ def test_every_section_figure_caption_is_unique(self):
         self.assertEqual(duplicates, {}, f"duplicate section captions: {duplicates}")
 
 
+    def test_every_section_has_a_score(self):
+        from src.marginalia import SECTION_FIGURES, SECTION_FIGURE_SCORES
+
+        unscored = set(SECTION_FIGURES) - set(SECTION_FIGURE_SCORES)
+        unattached = set(SECTION_FIGURE_SCORES) - set(SECTION_FIGURES)
+        self.assertEqual(unscored, set(), f"unscored sections: {sorted(unscored)}")
+        self.assertEqual(unattached, set(), f"scored but unattached: {sorted(unattached)}")
+
+    def test_every_section_score_in_range(self):
+        from src.marginalia import SECTION_FIGURE_SCORES
+
+        failures: list[str] = []
+        for title, entry in SECTION_FIGURE_SCORES.items():
+            if not isinstance(entry, tuple) or len(entry) != 2:
+                failures.append(f"{title!r}: not a (score, commentary) tuple")
+                continue
+            score, commentary = entry
+            if not isinstance(score, (int, float)) or not 0 <= score <= 10:
+                failures.append(f"{title!r}: score {score!r} outside [0, 10]")
+            if not isinstance(commentary, str) or not commentary.strip():
+                failures.append(f"{title!r}: empty commentary")
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+
+    def test_every_example_has_a_quality_score(self):
+        from src.example_loader import load_examples
+        from src.marginalia import EXAMPLE_QUALITY_SCORES
+
+        _, examples = load_examples()
+        slugs = {ex["slug"] for ex in examples}
+        unscored = slugs - set(EXAMPLE_QUALITY_SCORES)
+        ghost = set(EXAMPLE_QUALITY_SCORES) - slugs
+        self.assertEqual(unscored, set(), f"unscored examples: {sorted(unscored)}")
+        self.assertEqual(ghost, set(), f"scored but no example: {sorted(ghost)}")
+
+    def test_every_example_quality_score_in_range(self):
+        from src.marginalia import EXAMPLE_QUALITY_SCORES
+
+        failures: list[str] = []
+        for slug, entry in EXAMPLE_QUALITY_SCORES.items():
+            if not isinstance(entry, tuple) or len(entry) != 2:
+                failures.append(f"{slug}: not a tuple")
+                continue
+            score, commentary = entry
+            if not isinstance(score, (int, float)) or not 0 <= score <= 10:
+                failures.append(f"{slug}: score {score!r} outside [0, 10]")
+            if not isinstance(commentary, str) or not commentary.strip():
+                failures.append(f"{slug}: empty commentary")
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+
 class FigureCaptionContract(unittest.TestCase):
     """Contract 5b: every attachment caption is unique.
 
