Journey-faithful figures: 18 sections, one figure each, six prototype pages

Each of the six journeys now has its own prototype page with three
section figures that actually depict the section's conceptual shift —
not recycled lesson figures.

Fifteen new figures added to src/marginalia.py:

  Runtime
    program-output         source produces visible output
    identity-and-equality  same object vs equal objects
    operator-dispatch      a + b becomes a.__add__(b)

  Shapes
    container-questions    list/tuple/dict/set, each answers a different question
    reshape-pipeline       input → transform → result
    text-data-boundary     text in, structured value out

  Interfaces
    function-signature     args → body → return
    function-as-value      a second name binds to the same function object
    class-with-state       state and methods bundled behind one interface

  Types
    annotation-ghost       annotations describe; runtime accepts any object
    union-types            int | str | None — slot accepts one of several
    generic-preservation   the same T flows in and out of fn[T]

  Reliability
    exception-lanes        try/except/else/finally as parallel lanes
    context-bowtie         enter → body → exit; raise still routes through exit
    async-swimlane         loop and coroutine swap on await

Streams keeps the three figures shipped earlier (branch-fork,
loop-repetition, iter-protocol).

build_prototypes.py refactored: a single JOURNEY_SECTION_FIGURES map
keys section title → (figure_name, caption); build_journey(slug)
renders one prototype page per journey. Six pages added under
/prototyping/journey-{runtime,streams,shapes,interfaces,types,reliability}.html
plus index entries.

https://claude.ai/code/session_01MazwoRWAihW6dwso3fMCHE

Author: claude

public/prototyping/index.html

@@ -39,7 +39,7 @@
     <h1>Visual explainer prototypes</h1>
     <p class="meta">Real example pages with their attached figures, plus the design-review pages. The example pages all use the production layout: a cell with an attached figure stacks prose, figure, and code vertically; cells without figures keep today's prose|code grid.</p>
   </section>
-  <ul class="prototype-list"><li><a class="text-link" href="/prototyping/marginalia-gestalt.html"><strong>Marginalia gestalt</strong></a><p class="meta">Every journey and example as a card, drawn from the shared grammar. Pure design review.</p></li><li><a class="text-link" href="/prototyping/operators-polish-comparison.html"><strong>Operators alignment polish</strong></a><p class="meta">Side-by-side before/after for the tree-edge alignment fix; demonstrates Canvas.connect().</p></li><li><a class="text-link" href="/prototyping/example-mutability.html"><strong>Example · Mutability (canonical · between prose and code)</strong></a><p class="meta">Mutability lesson, figure between prose and code. Production layout: cell stacks vertically when a figure is attached.</p></li><li><a class="text-link" href="/prototyping/layout-above.html"><strong>Layout · figure above prose</strong></a><p class="meta">Variant: figure leads the cell, then prose, then code. Single-column stacking. Eye flow: see picture, read intuition, read code.</p></li><li><a class="text-link" href="/prototyping/layout-after-output.html"><strong>Layout · figure after output</strong></a><p class="meta">Variant: figure ends the cell as a visual summary after the output. Single-column stacking. Eye flow: read everything, then see the picture that ties it together.</p></li><li><a class="text-link" href="/prototyping/layout-banner-top.html"><strong>Layout · figure as banner above 2-col cell</strong></a><p class="meta">Variant: figure spans both columns as a banner above the cell; prose and code keep their 2-column grid below. Eye flow: illustrated header → 2-up reading.</p></li><li><a class="text-link" href="/prototyping/layout-banner-bottom.html"><strong>Layout · figure as banner below 2-col cell</strong></a><p class="meta">Variant: prose and code keep their 2-column grid; figure spans both columns as a footer. Eye flow: 2-up reading → illustrated summary.</p></li><li><a class="text-link" href="/prototyping/layout-prose-aside.html"><strong>Layout · figure floated inside prose</strong></a><p class="meta">Variant: small figure floats right inside the prose column; paragraphs flow around it. Code-stack continues in its own column. Eye flow: prose with embedded illustration, code beside.</p></li><li><a class="text-link" href="/prototyping/example-closures.html"><strong>Example · Closures</strong></a><p class="meta">Closures lesson with the closure-cell figure on cell 0. Inner function references the outer cell.</p></li><li><a class="text-link" href="/prototyping/example-for-loops.html"><strong>Example · For Loops</strong></a><p class="meta">For-loops lesson with the iterator-unroll figure on cell 1. Each next() advances the caret.</p></li><li><a class="text-link" href="/prototyping/example-slices.html"><strong>Example · Slices</strong></a><p class="meta">Slices lesson with the slice-ruler figure on cell 0. Adjacent slices split at index 3.</p></li><li><a class="text-link" href="/prototyping/journey-streams.html"><strong>Journey · Streams</strong></a><p class="meta">Streams journey with three section-faithful figures: branching for decisions, repetition for loop shapes, the iter/next protocol for streams.</p></li></ul>
+  <ul class="prototype-list"><li><a class="text-link" href="/prototyping/marginalia-gestalt.html"><strong>Marginalia gestalt</strong></a><p class="meta">Every journey and example as a card, drawn from the shared grammar. Pure design review.</p></li><li><a class="text-link" href="/prototyping/operators-polish-comparison.html"><strong>Operators alignment polish</strong></a><p class="meta">Side-by-side before/after for the tree-edge alignment fix; demonstrates Canvas.connect().</p></li><li><a class="text-link" href="/prototyping/example-mutability.html"><strong>Example · Mutability (canonical · between prose and code)</strong></a><p class="meta">Mutability lesson, figure between prose and code. Production layout: cell stacks vertically when a figure is attached.</p></li><li><a class="text-link" href="/prototyping/layout-above.html"><strong>Layout · figure above prose</strong></a><p class="meta">Variant: figure leads the cell, then prose, then code. Single-column stacking. Eye flow: see picture, read intuition, read code.</p></li><li><a class="text-link" href="/prototyping/layout-after-output.html"><strong>Layout · figure after output</strong></a><p class="meta">Variant: figure ends the cell as a visual summary after the output. Single-column stacking. Eye flow: read everything, then see the picture that ties it together.</p></li><li><a class="text-link" href="/prototyping/layout-banner-top.html"><strong>Layout · figure as banner above 2-col cell</strong></a><p class="meta">Variant: figure spans both columns as a banner above the cell; prose and code keep their 2-column grid below. Eye flow: illustrated header → 2-up reading.</p></li><li><a class="text-link" href="/prototyping/layout-banner-bottom.html"><strong>Layout · figure as banner below 2-col cell</strong></a><p class="meta">Variant: prose and code keep their 2-column grid; figure spans both columns as a footer. Eye flow: 2-up reading → illustrated summary.</p></li><li><a class="text-link" href="/prototyping/layout-prose-aside.html"><strong>Layout · figure floated inside prose</strong></a><p class="meta">Variant: small figure floats right inside the prose column; paragraphs flow around it. Code-stack continues in its own column. Eye flow: prose with embedded illustration, code beside.</p></li><li><a class="text-link" href="/prototyping/example-closures.html"><strong>Example · Closures</strong></a><p class="meta">Closures lesson with the closure-cell figure on cell 0. Inner function references the outer cell.</p></li><li><a class="text-link" href="/prototyping/example-for-loops.html"><strong>Example · For Loops</strong></a><p class="meta">For-loops lesson with the iterator-unroll figure on cell 1. Each next() advances the caret.</p></li><li><a class="text-link" href="/prototyping/example-slices.html"><strong>Example · Slices</strong></a><p class="meta">Slices lesson with the slice-ruler figure on cell 0. Adjacent slices split at index 3.</p></li><li><a class="text-link" href="/prototyping/journey-runtime.html"><strong>Journey · Runtime</strong></a><p class="meta">Programs run statements, names refer to objects, expressions become method calls.</p></li><li><a class="text-link" href="/prototyping/journey-streams.html"><strong>Journey · Streams</strong></a><p class="meta">Decisions branch values; loops repeat; iteration is a protocol behind for.</p></li><li><a class="text-link" href="/prototyping/journey-shapes.html"><strong>Journey · Shapes</strong></a><p class="meta">Containers answer different questions; reshaping is the everyday move; text becomes structured data.</p></li><li><a class="text-link" href="/prototyping/journey-interfaces.html"><strong>Journey · Interfaces</strong></a><p class="meta">Functions are named behavior; functions are values; classes bundle state with behavior.</p></li><li><a class="text-link" href="/prototyping/journey-types.html"><strong>Journey · Types</strong></a><p class="meta">Annotations describe but don&#x27;t enforce; unions cover alternatives; generics preserve shape across calls.</p></li><li><a class="text-link" href="/prototyping/journey-reliability.html"><strong>Journey · Reliability</strong></a><p class="meta">Failure is explicit; resources have boundaries; concurrency outlives single expressions.</p></li></ul>
 </article>
 
 </body>

public/prototyping/journey-interfaces.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Journey · Interfaces · Prototype</title>
+<link rel="stylesheet" href="/site.css">
+<style>
+  .prototype-banner {
+    margin: 0 0 var(--space-4);
+    padding: var(--space-2) var(--space-3);
+    background: var(--accent-soft);
+    border: 1px dashed var(--hairline);
+    border-radius: .5rem;
+    color: var(--muted);
+    font-size: .85rem;
+  }
+  .prototype-banner strong { color: var(--text); font-weight: 600; }
+  .prototype-banner a { color: inherit; }
+  /* Production layout for cells with figures: single-column stacking. */
+  .lp-cell.has-figure { grid-template-columns: 1fr; }
+  .cell-figure { margin: 0; padding: 0; }
+  .cell-figure svg { width: 100%; max-width: 360px; height: auto; display: block; }
+  .cell-figure figcaption { margin-top: var(--space-2); color: var(--muted); font-size: .92rem; font-style: italic; max-width: 56ch; }
+
+  .journey-section { display: grid; grid-template-columns: minmax(0, 1fr); gap: var(--space-4); }
+  @media (min-width: 900px) {
+    .journey-section { grid-template-columns: minmax(0, 1.4fr) minmax(220px, 320px); align-items: start; }
+  }
+  .journey-figure { margin: 0; padding: 0; }
+  .journey-figure svg { width: 100%; height: auto; display: block; }
+  .journey-figure figcaption { margin-top: var(--space-2); color: var(--muted); font-size: .85rem; font-style: italic; }
+
+</style>
+</head>
+<body>
+<div class="prototype-banner"><strong>Prototype</strong> · Interfaces journey with one section-faithful figure per section. Each figure captures the conceptual shift the section introduces. · <a href="/prototyping/">all prototypes</a></div>
+
+<article class="example-shell journey-page">
+  <div class="example-top"><a class="text-link" href="/">← Home</a></div>
+  <section class="example-intro">
+    <p class="eyebrow">Journey</p>
+    <h1>Interfaces</h1>
+    <p class="meta">This journey shows how Python grows from simple functions to callable APIs, object interfaces, protocols, and metaclasses.</p>
+  </section>
+  <section class="journey-section"><div><h2>Start with functions as named behavior.</h2><p class="meta">Functions are the first abstraction boundary because they name behavior and control how callers provide information.</p><ul class="journey-list"><li><a class="text-link journey-item-title" href="/examples/functions">Functions</a><p class="meta">package behavior behind a name</p></li><li><a class="text-link journey-item-title" href="/examples/keyword-only-arguments">Keyword-only Arguments</a><p class="meta">make important call-site choices explicit</p></li><li><a class="text-link journey-item-title" href="/examples/positional-only-parameters">Positional-only Parameters</a><p class="meta">hide parameter names that should remain implementation details</p></li><li><a class="text-link journey-item-title" href="/examples/args-and-kwargs">Args and Kwargs</a><p class="meta">accept flexible call shapes when forwarding or adapting APIs</p></li><li><a class="text-link journey-item-title" href="/examples/multiple-return-values">Multiple Return Values</a><p class="meta">return multiple related values as a tuple</p></li></ul></div><figure class="journey-figure"><svg viewBox="0 0 188 80" xmlns="http://www.w3.org/2000/svg"><line x1="0" y1="44" x2="25.0" y2="44.0" stroke="#521000" stroke-width="1.0"/><polygon points="32,44 25.0,46.8 25.0,41.2" fill="#521000"/><text x="16" y="36" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">args</text><rect x="34" y="26" width="110" height="36" fill="none" stroke="#521000" stroke-width="1.0"/><text x="40" y="23" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">DEF F(...)</text><line x1="144" y1="44" x2="169.0" y2="44.0" stroke="#521000" stroke-width="1.0"/><polygon points="176,44 169.0,46.8 169.0,41.2" fill="#521000"/><text x="160" y="36" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">return</text></svg><figcaption>A function is the first abstraction boundary: arguments in, body, return value out.</figcaption></figure></section><section class="journey-section"><div><h2>Use functions as values.</h2><p class="meta">Python functions can capture state, be passed around, and wrap other functions.</p><ul class="journey-list"><li><a class="text-link journey-item-title" href="/examples/closures">Closures</a><p class="meta">capture state in nested functions</p></li><li><a class="text-link journey-item-title" href="/examples/scope-global-nonlocal">Global and Nonlocal</a><p class="meta">control where assignment happens</p></li><li><a class="text-link journey-item-title" href="/examples/recursion">Recursion</a><p class="meta">solve self-similar problems with a base case</p></li><li><a class="text-link journey-item-title" href="/examples/lambdas">Lambdas</a><p class="meta">write small unnamed functions for expression positions</p></li><li><a class="text-link journey-item-title" href="/examples/decorators">Decorators</a><p class="meta">wrap behavior without changing call sites</p></li><li><p class="journey-gap-label">Gap · Partial functions</p><p class="meta">show how to pre-fill arguments with `functools.partial`</p></li></ul></div><figure class="journey-figure"><svg viewBox="0 0 200 92" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="22" width="80" height="36" fill="none" stroke="#521000" stroke-width="1.0"/><text x="6" y="19" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">FN</text><text x="40" y="44" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">def f</text><line x1="80" y1="40" x2="109.0" y2="40.0" stroke="#FF4801" stroke-width="1.4"/><polygon points="116,40 109.0,42.8 109.0,37.2" fill="#FF4801"/><rect x="118" y="26" width="80" height="28" fill="rgba(82, 16, 0, 0.05)" stroke="#521000" stroke-width="1.0"/><text x="158.0" y="44.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">g = fn</text><text x="105" y="76" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">second name binds to the same function</text></svg><figcaption>Functions are first-class values. A second name binds to the same function object.</figcaption></figure></section><section class="journey-section"><div><h2>Bundle behavior with state.</h2><p class="meta">Classes become useful when data and behavior need to move together behind a stable interface.</p><ul class="journey-list"><li><a class="text-link journey-item-title" href="/examples/classes">Classes</a><p class="meta">bundle state and behavior into a new object type</p></li><li><a class="text-link journey-item-title" href="/examples/inheritance-and-super">Inheritance and Super</a><p class="meta">reuse and extend behavior through parent classes</p></li><li><a class="text-link journey-item-title" href="/examples/dataclasses">Dataclasses</a><p class="meta">generate common methods for data containers</p></li><li><a class="text-link journey-item-title" href="/examples/properties">Properties</a><p class="meta">keep attribute syntax while adding computation or validation</p></li><li><a class="text-link journey-item-title" href="/examples/special-methods">Special Methods</a><p class="meta">connect objects to Python syntax and built-ins</p></li><li><a class="text-link journey-item-title" href="/examples/metaclasses">Metaclasses</a><p class="meta">customize class creation when ordinary class tools are not enough</p></li><li><p class="journey-gap-label">Gap · Descriptors</p><p class="meta">explain the protocol behind methods, properties, and managed attributes</p></li></ul></div><figure class="journey-figure"><svg viewBox="0 0 152 108" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="8" width="150" height="92" fill="none" stroke="#521000" stroke-width="1.0"/><text x="6" y="5" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">CLASS BOX</text><text x="12" y="26" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">STATE</text><rect x="12" y="32" width="126" height="22" fill="none" stroke="#521000" stroke-width="1.0"/><text x="75.0" y="47.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">x · y</text><text x="12" y="64" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">METHODS</text><rect x="12" y="70" width="126" height="22" fill="none" stroke="#521000" stroke-width="1.0"/><text x="75.0" y="85.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">move(...)</text></svg><figcaption>Classes group fields and methods so data and behavior move together behind one interface.</figcaption></figure></section>
+</article>
+
+</body>
+</html>