Render journey-section figures inline on /journeys/<slug>

claude · claude · commit 64360a4d8a49 · 2026-05-11T20:10:04.000Z
Production journey pages now show each section's conceptual figure
between the section heading and the example list, matching how
example pages show cell figures.

  src/marginalia.py: SECTION_FIGURES dict (24 entries keyed by
    section title) and render_for_section(title) helper. The dict
    is the single source of truth — moved out of
    scripts/build_prototypes.py, which now imports it.

  src/app.py: render_journey_page injects render_for_section(...)
    between the section's meta line and its example list.

  public/site.css: .journey-section-figure { max-width: 440px; }
    matches .cell-banner--1's ceiling, with the same caption
    typography as example banners.

  scripts/build_prototypes.py: imports SECTION_FIGURES from
    src/marginalia.py (renamed locally to JOURNEY_SECTION_FIGURES
    for the existing prototype builders); 109 lines of duplicate
    dict removed.

  tests/test_marginalia_geometry.py: SectionFigureContract
    (Contract 10) asserts every JOURNEYS section has a figure,
    every SECTION_FIGURES entry maps to a real FIGURES paint
    function, and every section caption is unique. The orphan-
    figure contract now recognises SECTION_FIGURES as a usage
    source.

Six journey pages × ~4 sections each → 24 figures now render on
production journey pages that previously had none. The contracts
keep the journey rubric (docs/journey-visualisation-rubric.md) and
the production rendering in lockstep. Suite is 57 tests, all green.
diff --git a/public/site.2cfe9ad1f9db.css b/public/site.2cfe9ad1f9db.css
diff --git a/public/site.css b/public/site.css
diff --git a/scripts/build_prototypes.py b/scripts/build_prototypes.py
@@ -22,6 +22,7 @@
     get_example,
     render_inline,
 )
+from marginalia import SECTION_FIGURES as JOURNEY_SECTION_FIGURES  # noqa: E402
 from marginalia import _render_svg  # noqa: E402
 
 OUT_DIR = ROOT / "public" / "prototyping"
@@ -252,115 +253,6 @@ def build_index() -> None:
 """
 
 
-# Each journey section maps to ONE figure that captures the section's
-# conceptual shift. Keys are section titles exactly as they appear in
-# JOURNEYS in app.py. Each value is (figure_name, caption).
-JOURNEY_SECTION_FIGURES: dict[str, tuple[str, str]] = {
-    # Runtime
-    "Start with executable evidence.": (
-        "program-output",
-        "Every page is a runnable program. The smallest mental model: source produces visible output.",
-    ),
-    "Separate value, identity, and absence.": (
-        "identity-and-equality",
-        "Two names can share one object (left, both `is` and `==` true) or hold two equal-but-distinct objects (right, only `==` true).",
-    ),
-    "Read expressions as object operations.": (
-        "operator-dispatch",
-        "Operators are method calls. `a + b` dispatches to `a.__add__(b)`; the data model exposes the syntax.",
-    ),
-    # Control Flow
-    "Choose between paths.": (
-        "branch-fork",
-        "A value flows through a predicate to one of several branches.",
-    ),
-    "Name and shape decisions.": (
-        "naming-decisions",
-        "The walrus binds a name while the surrounding expression uses its value: one expression, two outputs.",
-    ),
-    "Stop as soon as the answer is known.": (
-        "early-exit",
-        "The loop exits at the first match — break short-circuits the rest of the sequence.",
-    ),
-    # Iteration
-    "Choose the right loop shape.": (
-        "loop-repetition",
-        "Walk the sequence, run the body, return; the shape behind for and while.",
-    ),
-    "See the protocol behind `for`.": (
-        "iter-protocol",
-        "iter() exposes the iterator behind for; next() pulls one value at a time until exhausted.",
-    ),
-    "Compose lazy value streams.": (
-        "lazy-stream",
-        "Filters and maps compose without materialising intermediate lists; values flow through the pipeline only when next() pulls them.",
-    ),
-    # Workers — constraint-shaped sections; figures tentative.
-    "Replace unavailable process boundaries with portable evidence.": (
-        "workers-portable-evidence",
-        "Worker isolation breaks the usual cross-process pathways; the lesson preserves a captured value as portable evidence instead.",
-    ),
-    "Keep network lessons local to the protocol boundary.": (
-        "workers-protocol-local",
-        "Demonstrate the protocol shape (request and response) rather than calling out over the network.",
-    ),
-    "Preserve the lesson while respecting the runtime.": (
-        "workers-lesson-runtime",
-        "The lesson's evidence survives across the boundary that the worker runtime enforces.",
-    ),
-    # Shapes
-    "Pick the container that matches the question.": (
-        "container-questions",
-        "Each container answers a different question: ordered, fixed, lookup, unique.",
-    ),
-    "Move between shapes deliberately.": (
-        "reshape-pipeline",
-        "Most everyday code reshapes data: one input, one transform, one new value.",
-    ),
-    "Cross text and data boundaries.": (
-        "text-data-boundary",
-        "Programs receive text and produce structured data; parsing makes the boundary explicit.",
-    ),
-    # Interfaces
-    "Start with functions as named behavior.": (
-        "function-signature",
-        "A function is the first abstraction boundary: arguments in, body, return value out.",
-    ),
-    "Use functions as values.": (
-        "function-as-value",
-        "Functions are first-class values. A second name binds to the same function object.",
-    ),
-    "Bundle behavior with state.": (
-        "class-with-state",
-        "Classes group fields and methods so data and behavior move together behind one interface.",
-    ),
-    # Types
-    "Keep runtime and static analysis separate.": (
-        "annotation-ghost",
-        "Annotations describe expected types for tools; the runtime accepts any object regardless.",
-    ),
-    "Describe realistic data shapes.": (
-        "union-types",
-        "A typed slot can accept one of several shapes — `int | str | None` covers expected absence and alternatives.",
-    ),
-    "Scale annotations for reusable libraries.": (
-        "generic-preservation",
-        "A generic type variable preserves shape across a call: the same T flows in and out.",
-    ),
-    # Reliability
-    "Make failure explicit.": (
-        "exception-lanes",
-        "try, except, else, and finally as parallel lanes; the path traced through them is the actual control flow.",
-    ),
-    "Control resource and module boundaries.": (
-        "context-bowtie",
-        "A context manager pairs setup with reliable cleanup; the raise path still routes through __exit__.",
-    ),
-    "Handle operations that outlive one expression.": (
-        "async-swimlane",
-        "On await, the coroutine yields to the loop; the loop runs other work and resumes when the awaitable is ready.",
-    ),
-}
 
 
 def build_journey(slug: str) -> None:
diff --git a/src/app.py b/src/app.py
@@ -10,11 +10,11 @@
 try:
     from .asset_manifest import ASSET_PATHS
     from .examples import EXAMPLES, EXAMPLES_BY_SLUG, PYTHON_VERSION, REFERENCE_URL
-    from .marginalia import render_for_anchor
+    from .marginalia import render_for_anchor, render_for_section
 except ImportError:  # Cloudflare Python Workers import sibling modules from main's directory.
     from asset_manifest import ASSET_PATHS
     from examples import EXAMPLES, EXAMPLES_BY_SLUG, PYTHON_VERSION, REFERENCE_URL
-    from marginalia import render_for_anchor
+    from marginalia import render_for_anchor, render_for_section
 
 
 class AppResponse:
@@ -572,7 +572,8 @@ def render_journey_page(journey):
             else:
                 sentence = f"This gap should {description}."
                 rows.append(f'<li><p class="journey-gap-label">Gap · {html.escape(value)}</p><p class="meta">{html.escape(sentence)}</p></li>')
-        sections.append(f'<section class="journey-section"><h2>{html.escape(section["title"])}</h2><p class="meta">{html.escape(section["summary"])}</p><ul class="journey-list">{"".join(rows)}</ul></section>')
+        figure_html = render_for_section(section["title"])
+        sections.append(f'<section class="journey-section"><h2>{html.escape(section["title"])}</h2><p class="meta">{html.escape(section["summary"])}</p>{figure_html}<ul class="journey-list">{"".join(rows)}</ul></section>')
     content = f'''
 <article class="example-shell journey-page">
   <div class="example-top"><a class="text-link" href="/">← All examples</a><a class="text-link" href="{html.escape(REFERENCE_URL)}">Python docs reference</a></div>
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.be98c8af1bb8.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = 'c361f35f812c'
+ASSET_PATHS = {'SITE_CSS': '/site.2cfe9ad1f9db.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
+HTML_CACHE_VERSION = '815cee0ddd64'
diff --git a/src/marginalia.py b/src/marginalia.py
@@ -1890,6 +1890,134 @@ def render_for_anchor(slug: str, anchor: str) -> str:
     return f'<div class="cell-banner{count_class}">{"".join(figures)}</div>'
 
 
+# ─── Journey-section figures ──────────────────────────────────────────
+# One figure per journey section, keyed by section title. The figure
+# depicts the conceptual shift the section's examples share — the
+# journey-section rubric (docs/journey-visualisation-rubric.md) scores
+# these. Rendered inline on /journeys/<slug> between the section
+# heading and the example list. Reviewed all together on
+# /prototyping/journey-figures-gestalt.
+
+SECTION_FIGURES: dict[str, tuple[str, str]] = {
+    # Runtime
+    "Start with executable evidence.": (
+        "program-output",
+        "Every page is a runnable program. The smallest mental model: source produces visible output.",
+    ),
+    "Separate value, identity, and absence.": (
+        "identity-and-equality",
+        "Two names can share one object (left, both `is` and `==` true) or hold two equal-but-distinct objects (right, only `==` true).",
+    ),
+    "Read expressions as object operations.": (
+        "operator-dispatch",
+        "Operators are method calls. `a + b` dispatches to `a.__add__(b)`; the data model exposes the syntax.",
+    ),
+    # Control Flow
+    "Choose between paths.": (
+        "branch-fork",
+        "A value flows through a predicate to one of several branches.",
+    ),
+    "Name and shape decisions.": (
+        "naming-decisions",
+        "The walrus binds a name while the surrounding expression uses its value: one expression, two outputs.",
+    ),
+    "Stop as soon as the answer is known.": (
+        "early-exit",
+        "The loop exits at the first match — break short-circuits the rest of the sequence.",
+    ),
+    # Iteration
+    "Choose the right loop shape.": (
+        "loop-repetition",
+        "Walk the sequence, run the body, return; the shape behind for and while.",
+    ),
+    "See the protocol behind `for`.": (
+        "iter-protocol",
+        "iter() exposes the iterator behind for; next() pulls one value at a time until exhausted.",
+    ),
+    "Compose lazy value streams.": (
+        "lazy-stream",
+        "Filters and maps compose without materialising intermediate lists; values flow through the pipeline only when next() pulls them.",
+    ),
+    # Shapes
+    "Pick the container that matches the question.": (
+        "container-questions",
+        "Each container answers a different question: ordered, fixed, lookup, unique.",
+    ),
+    "Move between shapes deliberately.": (
+        "reshape-pipeline",
+        "Most everyday code reshapes data: one input, one transform, one new value.",
+    ),
+    "Cross text and data boundaries.": (
+        "text-data-boundary",
+        "Programs receive text and produce structured data; parsing makes the boundary explicit.",
+    ),
+    # Interfaces
+    "Start with functions as named behavior.": (
+        "function-signature",
+        "A function is the first abstraction boundary: arguments in, body, return value out.",
+    ),
+    "Use functions as values.": (
+        "function-as-value",
+        "Functions are first-class values. A second name binds to the same function object.",
+    ),
+    "Bundle behavior with state.": (
+        "class-with-state",
+        "Classes group fields and methods so data and behavior move together behind one interface.",
+    ),
+    # Types
+    "Keep runtime and static analysis separate.": (
+        "annotation-ghost",
+        "Annotations describe expected types for tools; the runtime accepts any object regardless.",
+    ),
+    "Describe realistic data shapes.": (
+        "union-types",
+        "A typed slot can accept one of several shapes — `int | str | None` covers expected absence and alternatives.",
+    ),
+    "Scale annotations for reusable libraries.": (
+        "generic-preservation",
+        "A generic type variable preserves shape across a call: the same T flows in and out.",
+    ),
+    # Reliability
+    "Make failure explicit.": (
+        "exception-lanes",
+        "try, except, else, and finally as parallel lanes; the path traced through them is the actual control flow.",
+    ),
+    "Control resource and module boundaries.": (
+        "context-bowtie",
+        "A context manager pairs setup with reliable cleanup; the raise path still routes through __exit__.",
+    ),
+    "Handle operations that outlive one expression.": (
+        "async-swimlane",
+        "On await, the coroutine yields to the loop; the loop runs other work and resumes when the awaitable is ready.",
+    ),
+    # Workers — constraint-shaped sections.
+    "Replace unavailable process boundaries with portable evidence.": (
+        "workers-portable-evidence",
+        "Worker isolation breaks the usual cross-process pathways; the lesson preserves a captured value as portable evidence instead.",
+    ),
+    "Keep network lessons local to the protocol boundary.": (
+        "workers-protocol-local",
+        "Demonstrate the protocol shape (request and response) rather than calling out over the network.",
+    ),
+    "Preserve the lesson while respecting the runtime.": (
+        "workers-lesson-runtime",
+        "The lesson's evidence survives across the boundary that the worker runtime enforces.",
+    ),
+}
+
+
+def render_for_section(section_title: str) -> str:
+    """HTML for a section figure on a journey page. Empty if no
+    figure is registered for this section title.
+    """
+    entry = SECTION_FIGURES.get(section_title)
+    if not entry:
+        return ""
+    name, caption = entry
+    cap = f"<figcaption>{html.escape(caption)}</figcaption>" if caption else ""
+    return f'<figure class="journey-section-figure">{_render_svg(name)}{cap}</figure>'
+
+
 # ─── 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
diff --git a/tests/test_marginalia_geometry.py b/tests/test_marginalia_geometry.py
@@ -266,15 +266,20 @@ def test_every_attachment_points_to_a_real_figure(self):
         self.assertEqual(orphan_refs, set(), f"attachments reference unknown figures: {sorted(orphan_refs)}")
 
     def test_no_unused_figure_paint_functions(self):
-        # A figure name counts as "used" if it appears in ATTACHMENTS
-        # (example-page wiring) or anywhere in scripts/build_prototypes.py
-        # (journey-section figures, banner prototypes, gestalt galleries).
+        # A figure name counts as "used" if it ships on an example page
+        # (ATTACHMENTS), a journey section (SECTION_FIGURES), or appears
+        # anywhere in scripts/build_prototypes.py (banner layouts and
+        # gestalt galleries that aren't covered by the structured
+        # registries).
         from pathlib import Path
 
+        from src.marginalia import SECTION_FIGURES
+
         prototype_src = (
             Path(__file__).resolve().parents[1] / "scripts" / "build_prototypes.py"
         ).read_text()
         used = {name for items in ATTACHMENTS.values() for _, name, _ in items}
+        used |= {name for name, _ in SECTION_FIGURES.values()}
         used |= {name for name in FIGURES if f'"{name}"' in prototype_src or f"'{name}'" in prototype_src}
         unused = set(FIGURES) - used
         self.assertEqual(
@@ -334,6 +339,44 @@ def test_every_stroke_width_is_from_the_locked_set(self):
         self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
 
 
+class SectionFigureContract(unittest.TestCase):
+    """Contract 10: every journey section in app.py JOURNEYS has a
+    figure in SECTION_FIGURES, and every SECTION_FIGURES entry maps
+    to a real FIGURES paint function.
+    """
+
+    def test_every_journey_section_has_a_figure(self):
+        from src.app import JOURNEYS
+        from src.marginalia import SECTION_FIGURES
+
+        section_titles = {s["title"] for j in JOURNEYS for s in j["sections"]}
+        missing = section_titles - set(SECTION_FIGURES)
+        self.assertEqual(
+            missing, set(),
+            f"journey sections without a figure: {sorted(missing)}",
+        )
+
+    def test_every_section_figure_points_to_a_real_paint_function(self):
+        from src.marginalia import SECTION_FIGURES
+
+        orphan_refs = {name for name, _ in SECTION_FIGURES.values()} - set(FIGURES)
+        self.assertEqual(
+            orphan_refs, set(),
+            f"SECTION_FIGURES references unknown figures: {sorted(orphan_refs)}",
+        )
+
+    def test_every_section_figure_caption_is_unique(self):
+        from collections import defaultdict
+        from src.marginalia import SECTION_FIGURES
+
+        caption_to_titles: dict[str, list[str]] = defaultdict(list)
+        for title, (_, caption) in SECTION_FIGURES.items():
+            if caption:
+                caption_to_titles[caption].append(title)
+        duplicates = {c: t for c, t in caption_to_titles.items() if len(t) > 1}
+        self.assertEqual(duplicates, {}, f"duplicate section captions: {duplicates}")
+
+
 class FigureCaptionContract(unittest.TestCase):
     """Contract 5b: every attachment caption is unique.
 
