Fourth coverage push: 100% (109/109); 103 figures; lessons captured

Designed figures for the last 19 examples that previously lacked a
figure — all the constraint-shaped / infrastructure / advanced-typing
slugs. Each got a tightened mechanism picture against the
example-figure rubric:

  package-tree        packages
  venv-boundary       virtual-environments
  subprocess-spawn    subprocesses
  logging-levels      logging
  aaa-pattern         testing
  protocol-layers     networking
  gil-lanes           threads-and-processes
  cast-escape         casts-and-any
  newtype-phantom     newtype
  overload-signatures overloads
  paramspec-preserve  paramspec
  literal-constrained literal-and-final
  callable-type       callable-types
  isinstance-check    runtime-type-checks
  collections-containers collections-module
  typed-dict-shape    structured-data-shapes
  csv-records         csv-data
  warning-signal      warnings
  object-lifecycle    object-lifecycle

These cells had been flagged "constraint-shaped, may not need figures";
revisiting found that most of them DO have a single mechanism worth
depicting (a tree, a boundary, a spawn arrow, a stack of layers, an
arrange-act-assert sequence). The two genuine principles in the set
(casts-and-any, newtype) got figures depicting the static/runtime gap
they exploit.

docs/lessons-learned.md gains a new "Visualisations and marginalia"
section: 15 lessons from this thread including the grammar rule,
SVG-sizing pipeline invariants, prose-vs-figcaption discipline,
emphasis scarcity, the two-rubric structure, constraint-shaped section
limits, contributor vs curator split, inline-between vs banner grammars,
centralised gestalt-page pattern, mapping-vs-promotion paths, the
test-class-string fix, scoring discipline, and the explicit "some
examples should never have figures" rule.

Final coverage:
  Examples:  109/109 attached (100%)
  Journeys:  24/24 section figures (100%)
  FIGURES:   103 registered
  39 unit tests pass

https://claude.ai/code/session_01MazwoRWAihW6dwso3fMCHE

Author: claude

docs/lessons-learned.md

@@ -84,3 +84,20 @@ git diff --check
 - Keep `README.md` focused on how to understand, verify, and deploy the project.
 - Keep this lessons document updated when a bug reveals a general rule.
 - Record user-visible changes in `CHANGELOG.md` before significant commits or releases.
+
+## Visualisations and marginalia
+
+- **A diagram set needs a grammar, not a collection of one-off layouts.** Hand-drawn SVGs drift in stroke weight, cell size, type-tag placement, arrow style. A locked `Canvas` grammar (palette, tokens, words, phrases, metrics) makes drift structurally impossible. Cards declare figures by composing primitives; the library guarantees consistency.
+- **Emit explicit `width`/`height` on every SVG; use `max-width: 100%` in CSS, never `width: 100%`.** Without `width`/`height` the browser stretches a small viewBox to fill its container, doubling text inside. This was the root cause of every "figure too big" report. The fix lives in `Canvas.to_svg()` and the CSS rules in `public/site.css`, `scripts/build_prototypes.py`, and `scripts/build_marginalia.py`.
+- **A figure's diagrammatic content must not duplicate its figcaption.** SVGs may carry functional labels (`stdout`, `iter()`, panel tags like `before` / `after`, type signatures like `x: int | str | None`). Full sentences describing the figure as a whole are prose and belong in the figcaption. Captions are the canonical voice. The exception is review-only pages (`marginalia-gestalt`) where cards have no figcaption; figures destined for promotion to production must drop their inline prose first.
+- **Emphasis is scarce.** With site `--accent` saturated for UI use, a coral arrow on every line reads as no emphasis at all. `closed_arrow` defaults to `emphasis=False`; figures opt in only for the single element the prose names. Same rule for accent dots, gates, and ring highlights.
+- **Soft fills should be neutral, not accent-tinted.** A 5% warm-brown tint reads as a quiet container. An accent-tinted soft fill makes every object box look highlighted, which breaks the scarcity rule a second way.
+- **Two rubrics, one craft section.** Journey-section figures depict a *conceptual shift* across multiple lessons; example-cell figures depict the *single move* the surrounding cell discusses. `docs/journey-visualisation-rubric.md` and `docs/example-figure-rubric.md` score each on 10 points: content fidelity, craft, context. Topic gates per kind of section / cell shape.
+- **Constraint-shaped sections resist mechanism figures.** Workers' "Preserve the lesson while respecting the runtime" is a principle, not a mechanism. Forcing figures on such sections scores below the 8.5 gate. Either reframe the section around a mechanism or accept the gap deliberately.
+- **Authoring stays on the contributor; figures stay on the curator.** Example markdown does not include figure references. `src/marginalia.py` holds `FIGURES` (paint functions) and `ATTACHMENTS` (slug → cell → figure → caption). Curating figures is a single-file edit that contributors never see.
+- **Inline between prose and code is the production layout; banners between cells is the prototyped richer grammar.** Cells with figures drop to single-column stacking (prose, figure, code) via `.lp-cell.has-figure { grid-template-columns: 1fr }`. Cells without figures keep today's `prose | code` 2-column grid bit-for-bit. The banner-between approach (`/prototyping/layout-banner-*`) supports multi-figure small-multiples between cells when one inline figure isn't enough.
+- **Centralised gestalt pages catch drift that page-by-page review misses.** `/prototyping/marginalia-gestalt`, `/prototyping/journey-figures-gestalt`, and `/prototyping/production-figures-gestalt` show every figure in three different framings. Seeing all section figures of a journey in one 3-up row exposes inconsistencies invisible across six tabs.
+- **Mapping reuses existing figures; promoting moves design to production.** Half of example coverage came from attaching existing FIGURES to new examples (no paint code). The other half from new paint code copied or designed from gestalt cards. Both paths must pass the rubric.
+- **Tests against the cell layout must allow the `has-figure` class.** When the renderer adds `has-figure` to cells with attached figures, assertions on the literal string `class="lesson-step lp-cell"` fail. Change those tests to check the substring `lesson-step lp-cell` so both variants match.
+- **Score what's shipping, not what was designed.** A scoring dict on the gestalt is design-time review. Production figures live in `src/marginalia.py` `FIGURES` and may have been redesigned during promotion. Scoring should track the production version with the gestalt as separate history.
+- **Some examples should never have figures.** Constraint-shaped, infrastructure-shaped, and aggregator-shaped slugs lack a single mechanism to depict. Force-fitting figures on them scores below the gate. Leave them figure-less and document why rather than ship weak figures.

public/prototyping/production-figures-gestalt.html

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.489bc3f7eb6d.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '9974d2516af6'
+HTML_CACHE_VERSION = '943aba25c847'

src/asset_manifest.py

@@ -979,6 +979,187 @@ def delete_name_erased(c: Canvas) -> None:
     c.cell(102, 60, "[1, 2, 3]", w=90, h=22, soft=True)
 
 
+# ─── Fourth coverage push: constraint-shaped examples ─────────────────
+
+
+def package_tree(c: Canvas) -> None:
+    """Packages · a directory with __init__.py becomes an importable package; submodules nest."""
+    c.frame(70, 0, 100, 22, label="mypackage")
+    c.mono(120, 14, "__init__.py")
+    c.stroke(120, 22, 40, 50)
+    c.stroke(120, 22, 120, 50)
+    c.stroke(120, 22, 200, 50)
+    c.cell(10, 50, "a.py", w=60, h=22)
+    c.cell(90, 50, "b.py", w=60, h=22)
+    c.cell(170, 50, "sub/", w=60, h=22, soft=True)
+
+
+def venv_boundary(c: Canvas) -> None:
+    """Virtual environments · a venv isolates a project's interpreter and packages from the system."""
+    c.frame(0, 0, 110, 70, label="project")
+    c.cell(12, 18, "code", w=84, h=20)
+    c.cell(12, 42, "requirements", w=84, h=20)
+    c.closed_arrow(110, 35, 142, 35, emphasis=True)
+    c.frame(144, 0, 130, 70, label="venv")
+    c.mono(209, 22, "python")
+    c.mono(209, 42, "site-packages")
+
+
+def subprocess_spawn(c: Canvas) -> None:
+    """Subprocesses · spawn a child process; capture stdout, stderr, and exit code as portable evidence."""
+    c.cell(0, 22, "parent", w=70, h=24)
+    c.closed_arrow(70, 34, 110, 34, emphasis=True)
+    c.label(90, 26, "spawn", anchor="middle")
+    c.cell(112, 22, "child process", w=110, h=24, soft=True)
+    c.closed_arrow(222, 34, 252, 34, emphasis=False)
+    c.cell(254, 22, "output", w=70, h=24)
+
+
+def logging_levels(c: Canvas) -> None:
+    """Logging · five levels; messages below the configured threshold are dropped."""
+    levels = [("CRITICAL", "50"), ("ERROR", "40"), ("WARNING", "30"), ("INFO", "20"), ("DEBUG", "10")]
+    for i, (name, num) in enumerate(levels):
+        c.cell(0, i * 22, name, w=120, h=20)
+        c.cell(122, i * 22, num, w=40, h=20, soft=True)
+
+
+def aaa_pattern(c: Canvas) -> None:
+    """Testing · arrange-act-assert: set up, run the behavior, compare the result."""
+    rows = [("arrange", "set up state"), ("act", "perform behavior"), ("assert", "compare result")]
+    for i, (label_text, body) in enumerate(rows):
+        c.cell(0, i * 24, label_text, w=80, h=22, soft=(i == 2))
+        c.closed_arrow(80, i * 24 + 11, 108, i * 24 + 11, emphasis=False)
+        c.cell(110, i * 24, body, w=140, h=22)
+
+
+def protocol_layers(c: Canvas) -> None:
+    """Networking · each layer in the stack hides the next; HTTP rests on TCP on IP on the link."""
+    layers = ["application · HTTP", "transport · TCP", "network · IP", "link"]
+    for i, name in enumerate(layers):
+        c.cell(0, i * 22, name, w=200, h=20)
+
+
+def gil_lanes(c: Canvas) -> None:
+    """Threads and processes · the GIL serialises Python bytecode across threads; processes run in parallel."""
+    c.lane(20, x0=0, x1=240, label="GIL")
+    c.lane(50, x0=0, x1=240, label="thread A")
+    c.lane(80, x0=0, x1=240, label="thread B")
+    c.cell(10, 44, "", w=30, h=12)
+    c.cell(70, 74, "", w=30, h=12)
+    c.cell(130, 44, "", w=30, h=12)
+    c.cell(190, 74, "", w=30, h=12)
+
+
+def cast_escape(c: Canvas) -> None:
+    """Casts and any · cast(T, x) tells the type checker to treat x as T; runtime is unaffected."""
+    c.cell(0, 22, "Any", w=70, h=24, ghost=True)
+    c.closed_arrow(70, 34, 110, 34, emphasis=True)
+    c.label(90, 26, "cast(T, x)", anchor="middle")
+    c.cell(112, 22, "T", w=70, h=24, soft=True)
+
+
+def newtype_phantom(c: Canvas) -> None:
+    """NewType · two static identities backed by the same runtime type."""
+    c.tag(0, 0, "runtime: int")
+    c.cell(0, 12, "42", w=60, h=24)
+    c.tag(0, 50, "static: UserId")
+    c.cell(0, 62, "UserId(42)", w=90, h=24, soft=True)
+
+
+def overload_signatures(c: Canvas) -> None:
+    """Overloads · @overload declares multiple signatures; one implementation routes to the right return type."""
+    c.tag(0, 0, "@overload")
+    c.cell(0, 12, "def f(x: int) -> str", w=180, h=20)
+    c.cell(0, 36, "def f(x: str) -> int", w=180, h=20)
+    c.closed_arrow(180, 32, 220, 32, emphasis=True)
+    c.cell(222, 22, "one impl", w=80, h=22, soft=True)
+
+
+def paramspec_preserve(c: Canvas) -> None:
+    """ParamSpec · the decorator preserves the wrapped function's full signature, parameter for parameter."""
+    c.cell(0, 22, "f(P)", w=50, h=24)
+    c.closed_arrow(50, 34, 80, 34, emphasis=True)
+    c.frame(82, 12, 100, 44, label="@dec")
+    c.mono(132, 36, "P preserved")
+    c.closed_arrow(182, 34, 212, 34, emphasis=True)
+    c.cell(214, 22, "wrapper(P)", w=80, h=24, soft=True)
+
+
+def literal_constrained(c: Canvas) -> None:
+    """Literal · the type narrows the slot to a fixed set of constant values."""
+    c.tag(0, 0, "Literal['red', 'green', 'blue']")
+    c.cell(0, 12, "x", w=40, h=24)
+    c.closed_arrow(40, 24, 70, 4, emphasis=False)
+    c.closed_arrow(40, 24, 70, 24, emphasis=False)
+    c.closed_arrow(40, 24, 70, 44, emphasis=False)
+    c.cell(72, 0, "'red'", w=70, h=20, soft=True)
+    c.cell(72, 22, "'green'", w=70, h=20, soft=True)
+    c.cell(72, 44, "'blue'", w=70, h=20, soft=True)
+
+
+def callable_type(c: Canvas) -> None:
+    """Callable types · the annotation captures the call shape: argument types and return type."""
+    c.tag(0, 0, "Callable[[int, str], bool]")
+    c.cell(0, 12, "(int, str)", w=100, h=22)
+    c.closed_arrow(100, 23, 130, 23, emphasis=False)
+    c.cell(132, 12, "bool", w=60, h=22)
+
+
+def isinstance_check(c: Canvas) -> None:
+    """Runtime type checks · isinstance asks the runtime; the answer is a bool, not a refinement."""
+    c.cell(0, 22, "isinstance(x, T)", w=140, h=24)
+    c.closed_arrow(140, 22, 170, 4, emphasis=True)
+    c.cell(172, 0, "True", w=60, h=20, soft=True)
+    c.closed_arrow(140, 46, 170, 56, emphasis=False)
+    c.cell(172, 50, "False", w=60, h=20)
+
+
+def collections_containers(c: Canvas) -> None:
+    """Collections module · four specialised containers for shapes the built-in types don't cover well."""
+    rows = [("deque", "fast appends both ends"), ("Counter", "key → count"), ("defaultdict", "missing key default"), ("namedtuple", "tuple with names")]
+    for i, (name, role) in enumerate(rows):
+        c.cell(0, i * 22, name, w=110, h=20)
+        c.cell(112, i * 22, role, w=170, h=20, soft=True)
+
+
+def typed_dict_shape(c: Canvas) -> None:
+    """Structured data shapes · TypedDict names each key's value type; the dict obeys the declared shape."""
+    c.frame(0, 0, 200, 86, label="User TypedDict")
+    rows = [("id", "int"), ("name", "str"), ("active", "bool")]
+    for i, (k, v) in enumerate(rows):
+        c.cell(14, 18 + i * 20, f"{k}: {v}", w=172, h=18)
+
+
+def csv_records(c: Canvas) -> None:
+    """CSV data · rows of records; each line has the same columns in the same order."""
+    c.tag(0, 0, "rows · records")
+    headers = ["id", "name", "score"]
+    rows = [["1", "Ada", "97"], ["2", "Bo", "88"], ["3", "Cy", "76"]]
+    for j, h in enumerate(headers):
+        c.cell(j * 70, 12, h, w=70, h=20, soft=True)
+    for i, r in enumerate(rows):
+        for j, v in enumerate(r):
+            c.cell(j * 70, 32 + i * 20, v, w=70, h=18)
+
+
+def warning_signal(c: Canvas) -> None:
+    """Warnings · a soft signal: the warning is reported, execution continues."""
+    c.cell(0, 22, "code path", w=90, h=24)
+    c.closed_arrow(90, 22, 120, 4, emphasis=False)
+    c.cell(122, 0, "DeprecationWarning", w=170, h=22, soft=True)
+    c.closed_arrow(90, 46, 120, 56, emphasis=True)
+    c.cell(122, 50, "execution continues", w=170, h=22)
+
+
+def object_lifecycle(c: Canvas) -> None:
+    """Object lifecycle · __init__ creates; the object lives while refcount > 0; __del__ finalises."""
+    c.cell(0, 22, "__init__", w=80, h=24)
+    c.closed_arrow(80, 34, 110, 34, emphasis=True)
+    c.cell(112, 22, "live · refcount > 0", w=140, h=24, soft=True)
+    c.closed_arrow(252, 34, 282, 34, emphasis=False)
+    c.cell(284, 22, "__del__", w=80, h=24)
+
+
 def lazy_stream(c: Canvas) -> None:
     """Iteration · Compose lazy value streams: filter and map flow values without materialising."""
     c.object_box(0, 26, "source", "[a,b,c]", w=78, h=24)
@@ -1086,6 +1267,26 @@ def lazy_stream(c: Canvas) -> None:
     "custom-exception-chain": (custom_exception_chain, 220, 90),
     "exception-group-peel": (exception_group_peel, 240, 50),
     "delete-name-erased": (delete_name_erased, 200, 84),
+    # Fourth coverage push: 19 figures for constraint-shaped examples
+    "package-tree": (package_tree, 240, 76),
+    "venv-boundary": (venv_boundary, 274, 76),
+    "subprocess-spawn": (subprocess_spawn, 324, 60),
+    "logging-levels": (logging_levels, 164, 124),
+    "aaa-pattern": (aaa_pattern, 250, 80),
+    "protocol-layers": (protocol_layers, 200, 100),
+    "gil-lanes": (gil_lanes, 244, 100),
+    "cast-escape": (cast_escape, 184, 56),
+    "newtype-phantom": (newtype_phantom, 96, 92),
+    "overload-signatures": (overload_signatures, 304, 64),
+    "paramspec-preserve": (paramspec_preserve, 294, 60),
+    "literal-constrained": (literal_constrained, 144, 76),
+    "callable-type": (callable_type, 196, 40),
+    "isinstance-check": (isinstance_check, 232, 76),
+    "collections-containers": (collections_containers, 284, 92),
+    "typed-dict-shape": (typed_dict_shape, 200, 92),
+    "csv-records": (csv_records, 212, 96),
+    "warning-signal": (warning_signal, 292, 80),
+    "object-lifecycle": (object_lifecycle, 366, 60),
 }
 
 
@@ -1497,6 +1698,83 @@ def lazy_stream(c: Canvas) -> None:
         "cell-0", "value-types",
         "Each literal form constructs an object of a specific type; the source spelling and the value type stay in sync.",
     )],
+    # Fourth coverage push: constraint-shaped examples
+    "packages": [(
+        "cell-0", "package-tree",
+        "A directory with __init__.py becomes an importable package; submodules and subpackages nest beneath it.",
+    )],
+    "virtual-environments": [(
+        "cell-0", "venv-boundary",
+        "A venv carries its own interpreter and site-packages, isolating a project's dependencies from the system.",
+    )],
+    "subprocesses": [(
+        "cell-0", "subprocess-spawn",
+        "subprocess.run spawns a child process and captures its stdout, stderr, and exit code as portable evidence.",
+    )],
+    "logging": [(
+        "cell-0", "logging-levels",
+        "Five severity levels; the logger's configured threshold drops everything below it.",
+    )],
+    "testing": [(
+        "cell-0", "aaa-pattern",
+        "arrange-act-assert: set up the state, perform the behavior under test, compare the result to expectations.",
+    )],
+    "networking": [(
+        "cell-0", "protocol-layers",
+        "Network protocols stack: HTTP rests on TCP, which rests on IP, which rests on the link layer.",
+    )],
+    "threads-and-processes": [(
+        "cell-0", "gil-lanes",
+        "Threads share memory but the GIL serialises Python bytecode; processes run in parallel with isolated memory.",
+    )],
+    "casts-and-any": [(
+        "cell-0", "cast-escape",
+        "cast(T, x) tells the type checker to treat x as T; the runtime is unaffected.",
+    )],
+    "newtype": [(
+        "cell-0", "newtype-phantom",
+        "NewType creates a distinct static identity backed by the same runtime type — UserId is int with a name.",
+    )],
+    "overloads": [(
+        "cell-0", "overload-signatures",
+        "@overload declares multiple call signatures; one underlying implementation routes input shape to return type.",
+    )],
+    "paramspec": [(
+        "cell-0", "paramspec-preserve",
+        "ParamSpec preserves the wrapped function's signature through a decorator, parameter for parameter.",
+    )],
+    "literal-and-final": [(
+        "cell-0", "literal-constrained",
+        "Literal narrows a slot to a fixed set of constant values; Final says the binding will not change.",
+    )],
+    "callable-types": [(
+        "cell-0", "callable-type",
+        "Callable[[A, B], R] captures the call shape: a tuple of argument types and one return type.",
+    )],
+    "runtime-type-checks": [(
+        "cell-0", "isinstance-check",
+        "isinstance and issubclass ask the runtime; the answer is a bool, not a static type refinement.",
+    )],
+    "collections-module": [(
+        "cell-0", "collections-containers",
+        "Four specialised containers for shapes the built-in types don't cover well: deque, Counter, defaultdict, namedtuple.",
+    )],
+    "structured-data-shapes": [(
+        "cell-0", "typed-dict-shape",
+        "TypedDict names each key's value type; the dict obeys the declared shape at static-check time.",
+    )],
+    "csv-data": [(
+        "cell-0", "csv-records",
+        "CSV files are rows of records; each line has the same columns in the same order.",
+    )],
+    "warnings": [(
+        "cell-0", "warning-signal",
+        "A warning is a soft signal: the message is reported, but execution continues unless filters elevate it.",
+    )],
+    "object-lifecycle": [(
+        "cell-0", "object-lifecycle",
+        "__init__ constructs the object; it lives while at least one reference holds it; __del__ runs when refcount hits zero.",
+    )],
 }