Extend marginalia contracts: text collisions, registration, grammar

Another pass over the figure library found three more bug classes the
geometry contracts didn't yet cover. Each becomes a new contract; the
existing fixes for the canonical bugs stay in place.

Contract 3 — no two text elements overlap (FigureTextCollisionContract).
  Catches narrow object_boxes whose tag and value compete for
  horizontal space. itertools-chain failed: "ITER A" (sans, w=30) and
  "1 · 2" (mono, w=31) couldn't both fit inside a 70px box with the
  tag-inside layout. Fix: revert that figure to tag_position="above"
  (the default) with iter A/B spaced 38px apart, canvas h 64→82.

Contracts 4a–d — FIGURES, ATTACHMENTS, SCORES stay in sync
(FigureRegistrationContract):
  * every attached slug is scored,
  * every scored slug is attached,
  * every attachment points to a figure that exists in FIGURES,
  * no FIGURES entry is orphan (a figure counts as used if it appears
    in ATTACHMENTS or anywhere in scripts/build_prototypes.py — the
    latter catches journey-section figures and banner-layout
    prototypes that share src/marginalia.py paint code).

Contracts 5a–c — grammar conformance (FigureGrammarContract):
  * every fill/stroke color is INK, INK_SOFT, EMPHASIS, SOFT_FILL,
    or "none",
  * every font-family is FONT_SERIF, FONT_MONO, or FONT_SANS,
  * every stroke-width is W_HAIRLINE (0.6), W_STROKE (1.0),
    W_EMPHASIS (1.4), or W_GHOST (0.5).
  All 109 figures already conform; the contract locks the system
  against future drift.

Suite is now 49 tests (was 41). Geometry, palette, fonts, stroke
weights, and registration consistency are all asserted on every
test run.

Author: claude

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.be98c8af1bb8.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '667afb62bbc5'
+HTML_CACHE_VERSION = '8a4057af1896'

src/asset_manifest.py

@@ -938,11 +938,11 @@ def yield_delegation(c: Canvas) -> None:
 
 def itertools_chain(c: Canvas) -> None:
     """Itertools · chain joins two iterables into one stream without materialising either."""
-    c.object_box(0, 0, "iter A", "1 · 2", w=70, h=24, tag_position="inside")
-    c.object_box(0, 34, "iter B", "3 · 4", w=70, h=24, tag_position="inside")
-    c.closed_arrow(70, 12, 100, 22, emphasis=False)
-    c.closed_arrow(70, 46, 100, 36, emphasis=False)
-    c.object_box(102, 16, "chain", "1 · 2 · 3 · 4", w=140, h=28, tag_position="inside")
+    c.object_box(0, 14, "iter A", "1 · 2", w=70, h=24)
+    c.object_box(0, 52, "iter B", "3 · 4", w=70, h=24)
+    c.closed_arrow(70, 26, 100, 36, emphasis=False)
+    c.closed_arrow(70, 64, 100, 54, emphasis=False)
+    c.object_box(102, 30, "chain", "1 · 2 · 3 · 4", w=140, h=28)
 
 
 def assertion_check(c: Canvas) -> None:
@@ -1329,7 +1329,7 @@ def lazy_stream(c: Canvas) -> None:
     "tuple-frozen": (tuple_frozen, 280, 48),
     "value-types": (value_types, 160, 116),
     "yield-delegation": (yield_delegation, 240, 84),
-    "itertools-chain": (itertools_chain, 246, 64),
+    "itertools-chain": (itertools_chain, 246, 82),
     "assertion-check": (assertion_check, 304, 76),
     "custom-exception-chain": (custom_exception_chain, 220, 90),
     "exception-group-peel": (exception_group_peel, 240, 50),

src/marginalia.py

@@ -20,7 +20,7 @@
 import re
 import unittest
 
-from src.marginalia import FIGURES
+from src.marginalia import ATTACHMENTS, FIGURES, SCORES
 from src.marginalia_grammar import Canvas
 
 ATTR = re.compile(r'([\w-]+)="([^"]+)"')
@@ -209,5 +209,124 @@ def test_no_text_partially_overlaps_a_rect(self):
         self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
 
 
+class FigureTextCollisionContract(unittest.TestCase):
+    """Contract 3: no two text elements in the same figure overlap.
+
+    Two text bounding boxes that overlap render on top of each other
+    and become unreadable. This catches narrow object_boxes whose tag
+    and value compete for horizontal space (the itertools-chain bug
+    where "ITER A" and "1 · 2" couldn't both fit in a 70px box).
+    """
+
+    def test_no_two_texts_overlap_in_a_figure(self):
+        failures: list[str] = []
+        for name, (paint, w, h) in FIGURES.items():
+            canvas = Canvas(w=w, h=h)
+            paint(canvas)
+            texts = []
+            for kind, attrs, content in parse_parts(canvas.parts):
+                if kind == "text":
+                    texts.append((element_bbox(kind, attrs, content), content))
+            for i, (abox, ac) in enumerate(texts):
+                for j in range(i + 1, len(texts)):
+                    bbox, bc = texts[j]
+                    if overlaps(abox, bbox):
+                        failures.append(f"{name}: texts {ac!r} and {bc!r} overlap at {abox} ∩ {bbox}")
+                        break
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+
+class FigureRegistrationContract(unittest.TestCase):
+    """Contract 4: FIGURES, ATTACHMENTS, SCORES stay in sync.
+
+    Every slug in ATTACHMENTS must be in SCORES, and vice versa.
+    Every figure name an attachment points to must exist in FIGURES.
+    Every paint function in FIGURES must be attached to at least one
+    slug — orphan paint functions accumulate as dead code and silently
+    fail to ship the design they encode.
+    """
+
+    def test_every_attached_slug_is_scored(self):
+        unscored = set(ATTACHMENTS) - set(SCORES)
+        self.assertEqual(unscored, set(), f"attached but unscored: {sorted(unscored)}")
+
+    def test_every_scored_slug_is_attached(self):
+        unattached = set(SCORES) - set(ATTACHMENTS)
+        self.assertEqual(unattached, set(), f"scored but unattached: {sorted(unattached)}")
+
+    def test_every_attachment_points_to_a_real_figure(self):
+        names = {name for items in ATTACHMENTS.values() for _, name, _ in items}
+        orphan_refs = names - set(FIGURES)
+        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).
+        from pathlib import Path
+
+        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 FIGURES if f'"{name}"' in prototype_src or f"'{name}'" in prototype_src}
+        unused = set(FIGURES) - used
+        self.assertEqual(
+            unused, set(),
+            f"figures defined but never rendered (orphan paint functions): {sorted(unused)}",
+        )
+
+
+class FigureGrammarContract(unittest.TestCase):
+    """Contract 5: every emitted SVG element uses only the locked
+    palette, font set, and stroke weights from marginalia_grammar.py.
+
+    Drift here is how the design system erodes — one cardinal red
+    here, one Inter font there, and suddenly the library reads as
+    independently authored.
+    """
+
+    def test_every_emitted_color_is_from_the_locked_palette(self):
+        from src.marginalia_grammar import INK, INK_SOFT, EMPHASIS, SOFT_FILL
+
+        allowed = {INK, INK_SOFT, EMPHASIS, SOFT_FILL, "none"}
+        failures: list[str] = []
+        for name, (paint, w, h) in FIGURES.items():
+            canvas = Canvas(w=w, h=h)
+            paint(canvas)
+            for kind, attrs, _ in parse_parts(canvas.parts):
+                for key in ("fill", "stroke"):
+                    color = attrs.get(key, "")
+                    if color and color not in allowed:
+                        failures.append(f"{name}: {kind} {key}={color!r}")
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+    def test_every_emitted_font_is_from_the_locked_set(self):
+        from src.marginalia_grammar import FONT_SERIF, FONT_MONO, FONT_SANS
+
+        allowed = {FONT_SERIF, FONT_MONO, FONT_SANS}
+        failures: list[str] = []
+        for name, (paint, w, h) in FIGURES.items():
+            canvas = Canvas(w=w, h=h)
+            paint(canvas)
+            for kind, attrs, _ in parse_parts(canvas.parts):
+                family = attrs.get("font-family", "")
+                if family and family not in allowed:
+                    failures.append(f"{name}: {kind} font-family={family!r}")
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+    def test_every_stroke_width_is_from_the_locked_set(self):
+        allowed = {"0.6", "1.0", "1.4", "0.5"}  # W_HAIRLINE, W_STROKE, W_EMPHASIS, W_GHOST
+        failures: list[str] = []
+        for name, (paint, w, h) in FIGURES.items():
+            canvas = Canvas(w=w, h=h)
+            paint(canvas)
+            for kind, attrs, _ in parse_parts(canvas.parts):
+                weight = attrs.get("stroke-width", "")
+                if weight and weight not in allowed:
+                    failures.append(f"{name}: {kind} stroke-width={weight!r}")
+        self.assertEqual(failures, [], "\n  " + "\n  ".join(failures))
+
+
 if __name__ == "__main__":
     unittest.main()