Banner-between grammar: union of Tufte, Knuth, Algebrica

Single rule: the cell stays a 2-column unit always; figures live BETWEEN
cells in banner rows that span both columns. A banner row holds one OR
many figures via an auto-fit grid. No more switching between 1, 2, and
3 column layouts within a page.

This is the intended union the user asked for:
- Knuth   — cells preserve the literate prose|code rhythm uninterrupted
- Tufte   — banner accepts a small-multiple of related figures
- Algebrica — quiet italic caption beneath each figure, generous
            whitespace above and below as a teaching pause

Three new prototypes on the mutability lesson, all with the same cell
content; only the banner configuration varies:

  /prototyping/layout-banner-single  one banner with one figure
                                      between cells 0 and 1
  /prototyping/layout-banner-pair    one banner with two figures —
                                      list mutates, tuple does not —
                                      a Tufte small-multiple
  /prototyping/layout-banner-trio    multiple banners across the
                                      walkthrough (lead-in, mid, summary)
                                      proving cells never reflow

Implementation:
- Added tuple-no-mutation figure to src/marginalia.py to pair with
  aliasing-mutation for the small-multiples demo
- scripts/build_prototypes.py: new banner() helper for 1+ figure rows;
  render_article gains a banners= parameter keyed by position
  (before, after-cell-N, after-walkthrough); BANNER_CSS supplies the
  auto-fit grid + dashed top/bottom border for visual rhythm
- docs/visual-explainer-spec.md rewritten: two-pattern grammar
  (banners between cells for example pages, figure beside heading
  for journey pages); the earlier inline-* / margin-overlay variants
  catalogued as the perils of switching column models

Production rendering is untouched in this commit — banner-between
lives in prototypes for review before migration.

https://claude.ai/code/session_01MazwoRWAihW6dwso3fMCHE

Author: claude

docs/visual-explainer-spec.md

@@ -8,91 +8,172 @@ between prose and code, which works at every viewport.
 
 ## Goals
 
+- **One column model per page type, fixed.** Example pages keep cells in
+  the prose|code 2-col grid; journey pages keep section heading + figure
+  in a 2-col grid. Figures never reflow the surrounding columns.
 - **Universal, not viewport-conditional.** A reader at any width sees the
-  same figure in the same place. No `@media` breakpoints; no overlay layer.
+  same figure in the same place. No `@media` breakpoints for figure
+  positioning; no overlay layer.
+- **Multiple figures supported.** Banners hold one, two, or three
+  figures via an auto-fit grid; small multiples are first-class.
 - **No contributor burden.** Example markdown stays as it is. Figures are
   curated separately by the project owner.
-- **Inline, between prose and code.** A figure sits in the same flow as the
-  cell prose and code; the cell stops being two columns and stacks
-  vertically so prose → figure → code reads top to bottom.
-- **Quiet by default.** Cells without figures keep the existing
-  `prose | code` grid unchanged. Today's pages render bit-for-bit identical
-  to before until a figure is attached.
+- **Quiet by default.** A page with no figures attached renders
+  bit-for-bit identical to today.
 - **Grammar reuse.** Figures are composed from the locked vocabulary in
   `src/marginalia_grammar.py`. No bespoke SVG.
 
 ## Layout strategy
 
-Each `.lp-cell` is normally `grid-template-columns: minmax(17rem, .85fr)
-minmax(0, 1fr)` — prose left, code right. When the cell has an attached
-figure, the renderer adds the `has-figure` class:
+Two patterns, one for each page type. Both keep their underlying column
+model fixed; figures slot into defined positions without disrupting it.
 
-```css
-.lp-cell.has-figure { grid-template-columns: 1fr; }
-```
+### Example pages — banners between cells
 
-Within that single column the children stack in document order: prose
-paragraph, figure (with optional caption), code-stack. Cells without a
-figure are not touched.
+Each `.lp-cell` stays `grid-template-columns: minmax(17rem, .85fr)
+minmax(0, 1fr)` — prose left, code right — **always**. Figures live in
+banner rows that sit between cells, not inside them. The banner spans
+the full content width and uses an auto-fit grid so it can hold one,
+two, or three figures as small multiples.
 
 ```
-┌── lp-cell (no figure, default) ──────────────────────┐
-│  prose paragraph         │  source / output          │
-└──────────────────────────────────────────────────────┘
-
-┌── lp-cell.has-figure (single column) ───────────────┐
-│  prose paragraph                                     │
-│  ┌──── cell-figure ────┐                             │
-│  │   svg               │                             │
-│  └─────────────────────┘                             │
-│  caption (italic, muted)                             │
-│  source                                              │
-│  output                                              │
-└──────────────────────────────────────────────────────┘
+[ cell 0 · prose | code ]
+─────── banner row ───────
+[ figure ]    optional caption
+─────────────────────────
+[ cell 1 · prose | code ]
 ```
 
-The figure renders inside the cell, between `<div class="lp-prose">` and
-`<div class="cell-code-stack">`:
+This matches the union of three influences:
+- *Knuth* — cells preserve the literate-program rhythm of prose and code
+  side by side, uninterrupted.
+- *Tufte* — the banner slot accepts a small-multiple of related figures
+  so contrasts and progressions read as one composition.
+- *Algebrica* — each banner figure carries a quiet italic caption beneath,
+  in the muted text colour, with generous whitespace above and below.
+
+Banner positions:
+
+| key                | renders                              |
+|--------------------|--------------------------------------|
+| `before`           | once, before the first cell           |
+| `after-cell-N`     | once, after cell N (zero-indexed)     |
+| `after-walkthrough`| once, after the last cell             |
+
+Each position holds **one or more** figures via `cell-banner` markup.
+Captions are per-figure.
 
 ```html
-<section class="lesson-step lp-cell has-figure">
-  <div class="lp-prose">…</div>
-  <figure class="cell-figure">
-    <svg>…</svg>
-    <figcaption>…</figcaption>
-  </figure>
-  <div class="cell-code-stack">…</div>
+<section class="literate-program">
+  <section class="lp-cell">prose | code</section>
+  <div class="cell-banner cell-banner--2">
+    <figure>
+      <svg>…</svg>
+      <figcaption>Mutable: change visible through any alias.</figcaption>
+    </figure>
+    <figure>
+      <svg>…</svg>
+      <figcaption>Immutable: aliases share a frozen value.</figcaption>
+    </figure>
+  </div>
+  <section class="lp-cell">prose | code</section>
 </section>
 ```
 
-`.cell-figure` keeps the SVG `width: 100%; max-width: 360px;` so figures
-display at a comfortable reading size on prose-column-wide cells without
-ballooning when the column is wider.
+```css
+.cell-banner {
+  margin: var(--space-5) 0;
+  padding: var(--space-4) 0;
+  border-block: 1px dashed var(--hairline-soft);
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: var(--space-4);
+  justify-items: center;
+}
+.cell-banner figure   { margin: 0; padding: 0; max-width: 360px; }
+.cell-banner svg      { width: 100%; height: auto; display: block; }
+.cell-banner figcaption {
+  margin-top: var(--space-2);
+  color: var(--muted);
+  font-size: .92rem;
+  font-style: italic;
+  max-width: 44ch;
+}
+.cell-banner--1 figure { max-width: 440px; }
+```
+
+The cell never reflows: cells without banners around them and cells
+between banners look identical to today's layout.
+
+### Journey pages — figure beside section heading
+
+Journey pages are not literate code; they are linear lists of items
+grouped under section headings. Here the figure lives **beside** the
+section heading in a 2-column row (heading-and-list on the left, figure
+on the right). The column model is fixed for the whole journey page:
+each section is a 2-col grid, every section the same shape.
+
+```css
+.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;
+  }
+}
+```
+
+One figure per section, faithful to the section's conceptual shift.
+This is the journey-streams pattern; reused unchanged for all six
+journeys (see `JOURNEY_SECTION_FIGURES` in `scripts/build_prototypes.py`).
+
+### Why these two, not five
+
+The earlier prototypes that mixed inline-above, inline-between,
+after-output, and prose-aside all switched the cell's column model
+when a figure was present. That created the perils of randomly
+oscillating between 1, 2, and 3 columns within the same page. The
+banner-between grammar fixes the column model and lets figure count
+vary instead. Adding a second or third figure changes the banner's
+internal grid (auto-fit handles 1/2/3+), but the cells around it
+remain unchanged — no reflow, no cognitive context-switch.
 
 ## Anchors and attachments
 
-`src/marginalia.py` declares which figures attach where:
+`src/marginalia.py` declares which figures attach where. The data shape
+will move from per-cell injection toward per-position banners:
 
 ```python
-ATTACHMENTS = {
-    "mutability": [
-        ("cell-0", "aliasing-mutation",
-         "Two names share one mutable list — appending through one name "
-         "changes the object visible through both."),
-    ],
-    # …
+# proposed shape — banners keyed by position, each holding 1+ figures
+BANNERS = {
+    "mutability": {
+        "after-cell-0": [
+            ("aliasing-mutation",
+             "Two names share one mutable list — appending through one "
+             "name changes the object visible through both."),
+            ("tuple-no-mutation",
+             "By contrast, a tuple is frozen — aliases share a value "
+             "no method can change in place."),
+        ],
+    },
 }
 ```
 
-Anchor identifiers:
+Banner positions:
 
-| anchor          | targets                              |
-|-----------------|--------------------------------------|
-| `cell-0`, `cell-1`, … | each literate-program cell, zero-indexed |
+| position           | renders                              |
+|--------------------|--------------------------------------|
+| `before`           | once, before the first cell           |
+| `after-cell-0`, …  | once, after cell N (zero-indexed)     |
+| `after-walkthrough`| once, after the last cell             |
 
-Other anchors (`intro`, `notes`, `playground`) are reserved for future use
-but only `cell-N` is wired today. Most slugs will start with no entry.
-Adding a figure is a one-line edit in `src/marginalia.py`.
+Each position is a list, not a single figure: the same banner may hold
+multiple figures as a small multiple. Most slugs will start empty.
+Adding a banner is a one-line edit in `src/marginalia.py`.
 
 ## Authoring model
 
@@ -125,26 +206,34 @@ from grammar primitives) and register it in `FIGURES`. Append a tuple of
 ## Files
 
 - `src/marginalia_grammar.py` — palette, tokens, words, phrases, metrics.
-  Aligned with `public/site.css` design tokens; cards use the four palette
-  constants and never pick colours directly.
-- `src/marginalia.py` — figure registry (`FIGURES`) and attachment map
-  (`ATTACHMENTS`). Exports `render_for_anchor(slug, anchor)` returning the
-  HTML the renderer injects into each cell.
-- `src/app.py` — `_render_walkthrough_cell` adds the `has-figure` class
-  and inserts the figure between prose and code-stack when an attachment
-  exists.
-- `public/site.css` — `.lp-cell.has-figure` and `.cell-figure` rules.
+  Aligned with `public/site.css` design tokens; figures use the four
+  palette constants and never pick colours directly.
+- `src/marginalia.py` — figure registry (`FIGURES`) and attachment map.
+  Exports `render_for_anchor(slug, anchor)` for the current cell-inline
+  layout; banner-rendering helpers will land alongside.
+- `src/app.py` — `_render_walkthrough_cell` is the current rendering
+  helper; the banner-between rollout will rename or replace it with a
+  walkthrough-level renderer that interleaves cells and banners.
+- `public/site.css` — currently `.lp-cell.has-figure` and `.cell-figure`
+  rules; will gain `.cell-banner` rules when the banner grammar ships
+  in production.
+- `scripts/build_prototypes.py` — already implements the banner grammar
+  and journey-section grammar so prototypes can validate it before
+  production migration.
 
 ## Edge cases
 
-- **Two figures on one cell.** Allowed; both render in document order
-  inside the `has-figure` cell. Use sparingly — three or more is a signal
-  the cell's prose is doing too much.
-- **No figure attached.** The cell keeps today's `prose | code` 2-column
-  grid; no DOM, CSS, or layout difference from before.
-- **Print.** The single-column stacking is print-friendly by default.
-- **Very narrow viewports (≤340px).** SVGs scale via `max-width: 100%`.
-  The grammar's intrinsic text sizes stay readable down to ~280px.
+- **Many figures in one banner.** Auto-fit grid handles 1 (centered,
+  larger), 2 (small-multiple pair), 3+ (wraps as content allows). More
+  than 3 in one banner is usually a signal that two adjacent banners
+  are clearer.
+- **No figures attached.** The page renders bit-for-bit identical to
+  today.
+- **Print.** Banners and cells both flow naturally in single-column
+  print contexts.
+- **Very narrow viewports (≤340px).** Banner figures stack via the
+  auto-fit grid; SVGs scale via `max-width: 100%`. Cells keep their
+  existing 980px breakpoint for collapsing the 2-col grid.
 
 ## Non-goals