Close the four diagram-grammar gaps

1. Emphasis scarcity is now counted semantically by the grammar
   (Canvas.accent_count) instead of reverse-engineered from SVG, where
   an arrow's shaft and a gate line are indistinguishable. Gates
   collectively count as one accent per figure; a lanes traced path
   and its terminal dot count as one mark. Two new contract tests
   enforce the counter and catch primitives that paint EMPHASIS
   without counting. This closes the blind spot where generator-ribbon
   shipped 3 uncounted gate lines and control-stop-boundary's gate was
   invisible to the contract.

2. Twin layouts are now phrases, so coordinate drift is structurally
   impossible: two_names_one_object (aliasing-mutation /
   tuple-no-mutation), type_triangle (class-triangle /
   metaclass-triangle), and mono_divider computes a character
   divider's x from the font advance instead of an eyeballed pixel.
   This normalizes two live drifts: the aliasing/tuple second-panel
   tag gap (8px vs the first panel's 6px) and metaclass-triangle
   sitting 2px lower and 10px wider-gapped than its class-triangle
   twin.

3. Text metrics are single-sourced: MONO_ADVANCE (exact, for
   positioning) and BBOX_ADVANCE/text_width (conservative, for the
   clipping/collision contracts) live in marginalia_grammar.py; the
   geometry contracts import them instead of redefining their own.

4. Figure SVGs now carry aria-hidden/focusable=false so screen
   readers get the figcaption (the canonical voice) instead of the
   SVG's internal text fragments out of context.

117 of 123 figures are geometry-identical; the 6 that changed are the
twin normalizations above. HTML_CACHE_VERSION regenerated.

Author: claude

docs/example-figure-rubric.md

@@ -138,8 +138,15 @@ the figure can merge.
 - **Stroke-weight discipline.** Only `W_HAIRLINE`, `W_STROKE`,
   `W_EMPHASIS`, `W_GHOST`. *Contract 5c.*
 - **Emphasis scarcity, enforced.** At most ONE accent mark
-  (`EMPHASIS`-coloured arrowhead, caret, dot, or rect stroke) per
-  figure. Was a soft v1 criterion; now hard. *Contract 9.*
+  (`EMPHASIS`-coloured arrowhead, caret, dot, traced path, or rect
+  stroke) per figure. Was a soft v1 criterion; now hard. The census
+  is semantic, counted by the grammar itself (`Canvas.accent_count`),
+  because an arrow's shaft and a standalone gate line are
+  indistinguishable in raw SVG. Two codified carve-outs: all gates in
+  a figure collectively count as ONE accent (repeated structural
+  punctuation — every pause point on a ribbon — reads as one system),
+  and a `lanes` traced path plus its terminal dot count as one mark.
+  A gate set plus any focal accent still fails. *Contract 9.*
 - **Banner-fit, enforced.** Every figure's intrinsic width
   (Canvas.w + 2 · PAD_X) must fit `.cell-banner--1`'s 440px max
   ceiling. *Contract 8.*

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.e87d4baf77e6.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.a4a7766e1b9b.js'}
-HTML_CACHE_VERSION = '35cf77d48ca5'
+HTML_CACHE_VERSION = 'c09a7489d1e1'

src/marginalia.py

@@ -34,36 +34,17 @@
 
 def aliasing_mutation(c: Canvas) -> None:
     """Two names binding to one mutable list, before and after a mutation."""
-    c.tag(0, 12, "before")
-    c.name_box(0, 18, "first")
-    c.name_box(0, 48, "second")
-    c.closed_arrow(60, 30, 86, 46, emphasis=False)
-    c.closed_arrow(60, 60, 86, 46, emphasis=False)
-    c.object_box(88, 32, "", '["python"]', w=88, h=28)
-
-    c.tag(0, 100, "after append")
-    c.name_box(0, 108, "first")
-    c.name_box(0, 138, "second")
-    c.closed_arrow(60, 120, 86, 136, emphasis=False)
-    c.closed_arrow(60, 150, 86, 136, emphasis=False)
-    c.object_box(88, 122, "", '["python","workers"]', w=130, h=28)
+    c.two_names_one_object(0, 18, "before", "first", "second", '["python"]', object_w=88)
+    c.two_names_one_object(0, 108, "after append", "first", "second",
+                           '["python","workers"]', object_w=130)
 
 
 def tuple_no_mutation(c: Canvas) -> None:
     """The contrast: two names binding to one immutable tuple — no mutation possible."""
-    c.tag(0, 12, "tuple — frozen")
-    c.name_box(0, 18, "first")
-    c.name_box(0, 48, "second")
-    c.closed_arrow(60, 30, 86, 46, emphasis=False)
-    c.closed_arrow(60, 60, 86, 46, emphasis=False)
-    c.object_box(88, 32, "", '("python",)', w=110, h=28)
-
-    c.tag(0, 100, "no .append")
-    c.name_box(0, 108, "first")
-    c.name_box(0, 138, "second")
-    c.closed_arrow(60, 120, 86, 136, emphasis=False)
-    c.closed_arrow(60, 150, 86, 136, emphasis=False)
-    c.object_box(88, 122, "", '("python",)', w=110, h=28)
+    c.two_names_one_object(0, 18, "tuple — frozen", "first", "second",
+                           '("python",)', object_w=110)
+    c.two_names_one_object(0, 108, "no .append", "first", "second",
+                           '("python",)', object_w=110)
     c.label(150, 170, "tuples raise AttributeError", anchor="middle")
 
 
@@ -597,14 +578,7 @@ def dataclass_fields(c: Canvas) -> None:
 
 def class_triangle(c: Canvas) -> None:
     """Classes · instance → class → type — every Python value sits on this triangle."""
-    c.dot(20, 28)
-    c.label(20, 54, "instance", anchor="middle")
-    c.closed_arrow(26, 28, 86, 28, emphasis=False)
-    c.frame(88, 10, 60, 36, label="class")
-    c.mono(118, 32, "Class")
-    c.closed_arrow(148, 28, 208, 28, emphasis=False)
-    c.frame(210, 10, 60, 36, label="type")
-    c.mono(240, 32, "type")
+    c.type_triangle("type", "type")
 
 
 def exception_cause_context(c: Canvas) -> None:
@@ -729,17 +703,15 @@ def sort_stability(c: Canvas) -> None:
 def kw_only_separator(c: Canvas) -> None:
     """Keyword-only arguments · `*` divides positional from keyword-only."""
     c.mono(0, 18, "def f(a, b, *, c, d): …", anchor="start")
-    # JetBrains Mono advances ~6px per char at fs=10; '*' sits at index 12.
-    c.dashed(75, 22, 75, 38)
+    c.mono_divider(0, 12, 22, 38)  # the '*' sits at index 12
     c.label(33, 50, "positional or kw", anchor="middle")
     c.label(120, 50, "keyword only", anchor="middle")
 
 
 def positional_only_separator(c: Canvas) -> None:
     """Positional-only parameters · `/` divides positional-only from positional-or-kw."""
     c.mono(0, 18, "def f(a, b, /, c, d): …", anchor="start")
-    # JetBrains Mono advances ~6px per char at fs=10; '/' sits at index 12.
-    c.dashed(75, 22, 75, 38)
+    c.mono_divider(0, 12, 22, 38)  # the '/' sits at index 12
     c.label(33, 50, "positional only", anchor="middle")
     c.label(120, 50, "positional or kw", anchor="middle")
 
@@ -899,14 +871,7 @@ def property_fork(c: Canvas) -> None:
 
 def metaclass_triangle(c: Canvas) -> None:
     """Metaclasses · instance → class → metaclass; the metaclass is the type of the class."""
-    c.dot(20, 30)
-    c.label(20, 56, "instance", anchor="middle")
-    c.closed_arrow(26, 30, 86, 30, emphasis=False)
-    c.frame(88, 12, 60, 36, label="class")
-    c.mono(118, 34, "Class")
-    c.closed_arrow(148, 30, 218, 30, emphasis=False)
-    c.frame(220, 12, 80, 36, label="metaclass")
-    c.mono(260, 34, "type")
+    c.type_triangle("metaclass", "type", third_w=80)
 
 
 def sys_path_resolution(c: Canvas) -> None:

src/marginalia_grammar.py

@@ -65,12 +65,73 @@
 SIZE_TAG = 8
 BASELINE = 4  # add to box-center y to render text vertically centered
 
+# ─── Text metrics ──────────────────────────────────────────────────────
+# Single source of truth for character advance. Paint code uses
+# MONO_ADVANCE (the font's exact advance) to compute positions; the
+# geometry contracts use BBOX_ADVANCE (deliberately conservative
+# over-estimates) to detect clipping and collision. Keeping both here —
+# instead of one in a paint comment and one in the test file — means a
+# recalibration happens in one place and both consumers move together.
+MONO_ADVANCE = 0.6  # JetBrains Mono advances 600/1000 units per em.
+BBOX_ADVANCE = {
+    "mono": 0.62,        # JetBrains Mono / IBM Plex Mono
+    "sans_upper": 0.65,  # Source Sans Pro uppercase (tag font)
+    "sans": 0.55,        # Source Sans Pro mixed-case (label font)
+    "serif": 0.52,       # Iowan Old Style / Charter italic
+}
+
+
+def font_class(family: str) -> str:
+    if "Mono" in family or "monospace" in family:
+        return "mono"
+    # "sans-serif" contains "serif" as a substring; check sans first
+    # so the system-sans fallback string doesn't misclassify.
+    if "sans" in family.lower():
+        return "sans"
+    if "serif" in family or "Iowan" in family or "Charter" in family:
+        return "serif"
+    return "sans"
+
+
+def text_width(content: str, family: str, size: float, tracking: float = 0.0) -> float:
+    """Conservative rendered width of a text run, for bbox math.
+
+    Upper-cased sans glyphs (the tag font: LOOP, INT, …) advance ~18%
+    wider than mixed-case sans; differentiating the two keeps the
+    contracts tight enough to catch real clips without over-flagging
+    every mixed-case label that kisses a sibling rect.
+    """
+    klass = font_class(family)
+    if klass == "sans" and content == content.upper() and any(ch.isalpha() for ch in content):
+        per_char = BBOX_ADVANCE["sans_upper"] * size
+    else:
+        per_char = BBOX_ADVANCE[klass] * size
+    return (per_char + tracking) * len(content)
+
 
 @dataclass
 class Canvas:
     w: int = 320
     h: int = 110
     parts: list[str] = field(default_factory=list)
+    # Semantic accent census. Every primitive that paints EMPHASIS
+    # increments _accents (or sets _gates_painted); the scarcity
+    # contract asserts accent_count() <= 1 from here instead of trying
+    # to reverse-engineer marks from SVG output, where an arrow's
+    # shaft+head pair and a standalone gate line are indistinguishable.
+    _accents: int = 0
+    _gates_painted: bool = False
+
+    def accent_count(self) -> int:
+        """Number of accent marks on the canvas, per the scarcity rule.
+
+        Gates are repeated structural punctuation — every pause point on
+        a ribbon, in every ribbon of the figure — and read as one system,
+        so all gates collectively count as a single accent. A gate set
+        plus any focal accent (emphasis arrow, caret, dot, traced path)
+        is still two marks competing for attention, and still fails.
+        """
+        return self._accents + (1 if self._gates_painted else 0)
 
     # ── tokens (private; cards should not reach for these) ────────────
     def _add(self, s: str) -> None:
@@ -98,6 +159,8 @@ def dashed(self, x1, y1, x2, y2):
         self._line(x1, y1, x2, y2, weight=W_HAIRLINE, dash=DASH)
 
     def dot(self, x, y, *, emphasis=False):
+        if emphasis:
+            self._accents += 1
         self._add(f'<circle cx="{x}" cy="{y}" r="{DOT_R}" fill="{EMPHASIS if emphasis else INK}"/>')
 
     def tick(self, x, y, *, length=TICK_LEN):
@@ -123,6 +186,8 @@ def closed_arrow(self, x1, y1, x2, y2, *, emphasis=False):
         per figure — the one mark the surrounding prose explicitly names.
         Saturated --accent strokes everywhere break visual scarcity.
         """
+        if emphasis:
+            self._accents += 1
         color = EMPHASIS if emphasis else INK
         weight = W_EMPHASIS if emphasis else W_STROKE
         dx, dy = x2 - x1, y2 - y1
@@ -214,9 +279,24 @@ def caret(self, x, y_top, *, emphasis=True):
         prose only names one of them — the others paint in ink so the
         scarce-emphasis rule still holds.
         """
+        if emphasis:
+            self._accents += 1
         fill = EMPHASIS if emphasis else INK
         self._add(f'<polygon points="{x},{y_top - 1} {x - 4},{y_top - 7} {x + 4},{y_top - 7}" fill="{fill}"/>')
 
+    def mono_divider(self, x_start, index, y_top, y_bot, *, size=SIZE_MONO):
+        """Dashed vertical centred on character `index` of a start-anchored
+        mono string drawn at x_start.
+
+        The x is computed from the font's advance (MONO_ADVANCE), not
+        eyeballed: hand-tuned positions drift, computed positions match
+        the rendered glyph. Returns the computed x.
+        """
+        advance = MONO_ADVANCE * size
+        x = x_start + index * advance + advance / 2
+        self.dashed(x, y_top, x, y_bot)
+        return x
+
     def register(self, x, y, w, *, divisions=None, between=False):
         """Hairline with regular ticks."""
         self.hairline(x, y, x + w, y)
@@ -251,6 +331,7 @@ def frame(self, x, y, w, h, *, label=None, ghost=False):
 
     def gate(self, x, y_top, y_bot):
         """Vertical EMPHASIS line crossing a ribbon."""
+        self._gates_painted = True
         self._line(x, y_top, x, y_bot, color=EMPHASIS, weight=W_EMPHASIS)
 
     def ribbon(self, x, y, w, *, h=30, gates=(), soft_segments=()):
@@ -281,6 +362,37 @@ def bind(self, x, y, name, type_tag, value, *, object_w=OBJECT_W, gap=40):
         self.closed_arrow(nx + 2, ny, ox - 2, oy)
         return (x, y, nx + gap + object_w, y + OBJECT_H)
 
+    def two_names_one_object(self, x, y, tag_text, name_a, name_b, value, *, object_w=OBJECT_W):
+        """Two names bound to one shared object — the aliasing picture.
+
+        Twin panels and twin figures (aliasing-mutation,
+        tuple-no-mutation) must keep this layout coordinate-identical;
+        composing it as a phrase makes drift structurally impossible.
+        y is the top of the first name box; the tag paints 6 above it.
+        """
+        if tag_text:
+            self.tag(x, y - 6, tag_text)
+        self.name_box(x, y, name_a)
+        self.name_box(x, y + 30, name_b)
+        self.closed_arrow(x + NAME_W, y + 12, x + NAME_W + 26, y + 28, emphasis=False)
+        self.closed_arrow(x + NAME_W, y + 42, x + NAME_W + 26, y + 28, emphasis=False)
+        self.object_box(x + NAME_W + 28, y + 14, "", value, w=object_w, h=28)
+
+    def type_triangle(self, third_label, third_value, *, third_w=60):
+        """instance → class → <third> — the triangle shared by the
+        class-triangle / metaclass-triangle twin figures. The shared
+        coordinates live here so the twins cannot drift apart; only the
+        third frame's label, value, and width vary.
+        """
+        self.dot(20, 28)
+        self.label(20, 54, "instance", anchor="middle")
+        self.closed_arrow(26, 28, 86, 28, emphasis=False)
+        self.frame(88, 10, 60, 36, label="class")
+        self.mono(118, 32, "Class")
+        self.closed_arrow(148, 28, 208, 28, emphasis=False)
+        self.frame(210, 10, third_w, 36, label=third_label)
+        self.mono(210 + third_w / 2, 32, third_value)
+
     def dispatch(self, x, y, src, dst, *, src_w=70, dst_w=120):
         """Source form → method form."""
         self.object_box(x, y, "", src, w=src_w, soft=False)
@@ -322,9 +434,13 @@ def lanes(self, ys_labels, *, x0=40, x1=300, path=None):
         for y, lab in ys_labels:
             self.lane(y, x0=x0, x1=x1, label=lab)
         if path:
+            # The traced path and its terminal dot are one mark: count
+            # once here and paint the dot directly so dot() doesn't
+            # count it a second time.
+            self._accents += 1
             d = " ".join(("M" if i == 0 else "L") + f"{px},{py}" for i, (px, py) in enumerate(path))
             self._add(f'<path d="{d}" stroke="{EMPHASIS}" stroke-width="{W_EMPHASIS}" fill="none"/>')
-            self.dot(path[-1][0], path[-1][1], emphasis=True)
+            self._add(f'<circle cx="{path[-1][0]}" cy="{path[-1][1]}" r="{DOT_R}" fill="{EMPHASIS}"/>')
 
     # ── render ────────────────────────────────────────────────────────
     # Figures render at INTRINSIC_SCALE × their viewBox dimensions. The
@@ -351,9 +467,14 @@ def to_svg(self) -> str:
         vb_h = self.h + pad_top + pad_bottom
         out_w = round(vb_w * self.INTRINSIC_SCALE)
         out_h = round(vb_h * self.INTRINSIC_SCALE)
+        # aria-hidden: the figcaption is the canonical voice for every
+        # figure; without it screen readers walk the SVG's internal
+        # <text> fragments ("STR", "next()", …) out of context before
+        # reaching the caption.
         return (
             f'<svg viewBox="-{pad_x} -{pad_top} {vb_w} {vb_h}" '
             f'width="{out_w}" height="{out_h}" '
+            f'aria-hidden="true" focusable="false" '
             f'xmlns="http://www.w3.org/2000/svg">'
             + "".join(self.parts)
             + "</svg>"