ea 0.3.1 → 0.5.0

data/TODO.diagrams/01-xmi-extension-elements-parsing.md

@@ -0,0 +1,67 @@
+# 01 - Parse XMI Extension Elements Block
+
+## Status: DONE (2026-07-21)
+
+## Problem
+
+EA's XMI stores diagram placement data inside an `<xmi:Extension>`
+block, under `<elements>/<element>` rows. Each row carries:
+
+- `geometry="Left=X;Top=Y;Right=X2;Bottom=Y2;imgL=..;imgT=..;imgR=..;imgB=..;"`
+  (pixel bounds + image bounds with 25 px padding)
+- `subject="EAID_..."` (the model element this placement refers to)
+- `seqno="N"` (z-order)
+- `style="BCol=<int>;font=<name>;fontsz=<int>;bold=0;italic=0;LWth=<int>;.."`
+  (EA packed style)
+
+For connectors, the same row shape carries:
+- `geometry="SX=..;SY=..;EX=..;EY=..;EDGE=N;$LLB=..;$LLT=..;LRT=..;LRB=..;Path=;"`
+- `style="Mode=3;SOID=<source DUID>;EOID=<target DUID>;Color=-1;LWidth=2;"`
+
+Our `Ea::Sources::Xmi::DiagramBuilder` currently reads only the
+UML-DI `<owned_element>/<bounds>` tree, which doesn't include any
+of this rich placement/style data. Result: SVG rendering from XMI
+sources is missing colors, fonts, bend routing, label positions,
+and proper element placement.
+
+## Approach
+
+Extend the XMI source adapter to walk the `<xmi:Extension>`
+block's `<elements>` rows for each diagram. Build a parallel
+`Ea::Model::DiagramElement` per row, populating:
+
+- `bounds` from `Left/Top/Right/Bottom`
+- `model_element_ref` from `subject` (resolved to model id)
+- `style` hash including `BCol`, `font`, `fontsz`, `bold`, `italic`,
+  `LWth`, `LCol` (line color)
+- A new `image_bounds` field carrying the `imgL/imgT/imgR/imgB`
+  padded bounds (EA's visual box, vs. the logical bounds)
+
+For connector rows, build `Ea::Model::DiagramConnector` with:
+- `relationship_ref` from `subject`
+- Source/target resolved via `SOID`/`EOID` → DUID → placed element
+- Waypoints computed from the SX/SY/EX/EY deltas + the source and
+  target element edge centers (matching EA's rendering math)
+- Style hash with `Color`, `LWidth`, `Mode`
+
+## Files
+
+- `lib/ea/sources/xmi/extension_elements.rb` (new — walks the
+  extension block, returns typed rows)
+- `lib/ea/sources/xmi/extension_geometry_parser.rb` (new — parses
+  `geometry="..."` packed string into a typed struct)
+- `lib/ea/sources/xmi/extension_style_parser.rb` (new — parses
+  `style="..."` packed string into a typed struct)
+- `lib/ea/sources/xmi/diagram_builder.rb` (updated — uses
+  extension data when present, falls back to umldi otherwise)
+- `lib/ea/model/diagram_element.rb` (extended — add
+  `image_bounds` field)
+- `spec/ea/sources/xmi/extension_*_spec.rb`
+
+## Verification
+
+- Unit specs: parse a known geometry/style string, assert typed
+  struct matches.
+- Integration: load `plateau_all_packages_export.xmi`, find diagram
+  `EAID_0016F797_...`, assert every placed element has bounds +
+  style populated.

data/TODO.diagrams/02-diagram-element-rich-model.md

@@ -0,0 +1,61 @@
+# 02 - Rich DiagramElement / DiagramConnector Model
+
+## Status: DONE (2026-07-21, folded into TODO 03)
+
+## Problem
+
+The current `Ea::Model::DiagramElement` carries only `bounds` and
+an untyped `style` hash. EA's renderer needs:
+
+- `image_bounds` (the imgL/imgT/imgR/imgB padded rect — distinct
+  from the logical Left/Top/Right/Bottom rect)
+- `background_color` (decoded from `BCol` BGR integer → RGB hex)
+- `font_family`, `font_size`, `font_bold`, `font_italic`
+- `line_color`, `line_width`
+- `z_order` (seqno)
+- `label_inset` (the offset from the bounds origin where text
+  should start; EA convention is x+5, y+17 for the first line)
+
+For `DiagramConnector`:
+- `source_anchor`, `target_anchor` (which edge of the source/target
+  element the line attaches to — top/right/bottom/left)
+- `source_duid`, `target_duid` (so the renderer can resolve back to
+  placed elements without re-walking the model)
+- `label_boxes` (the four LRT/LRB/LLT/LLB label rectangles with
+  their text content decoded)
+
+## Approach
+
+Extend the existing types (don't replace — backward compat for the
+QEA adapter which doesn't populate these yet):
+
+- `DiagramElement`: add `image_bounds`, `background_color`,
+  `font_family`, `font_size`, `font_bold`, `font_italic`,
+  `line_color`, `line_width`, `z_order`
+- `DiagramConnector`: add `source_anchor`, `target_anchor`,
+  `source_duid`, `target_duid`, `label_boxes` (collection)
+
+The QEA adapter populates these from its `objectstyle` packed
+string (existing `DiagramStyleParser`); the XMI adapter populates
+them from the `<xmi:Extension>/<elements>` style attribute.
+
+The renderer reads the typed fields directly — no more parsing at
+render time.
+
+## Files
+
+- `lib/ea/model/diagram_element.rb`
+- `lib/ea/model/diagram_connector.rb`
+- `lib/ea/model/label_box.rb` (new)
+- `lib/ea/sources/qea/diagram_builder.rb` (populate the new fields)
+- `lib/ea/sources/qea/diagram_style_parser.rb` (extend to typed
+  accessors, not just a hash)
+- `spec/ea/model/diagram_element_spec.rb`
+- `spec/ea/model/diagram_connector_spec.rb`
+
+## Verification
+
+- Round-trip: model JSON includes all new fields; deserialize
+  preserves them.
+- QEA adapter spec: every placed element has a non-nil
+  `background_color`.

data/TODO.diagrams/02-polygon-over-rendering.md

@@ -0,0 +1,29 @@
+# TODO-D 02 - Polygon over-rendering
+
+## Status: COMPLETE (2026-07-26)
+
+## Root cause
+
+Two bugs caused polygon over-rendering:
+
+1. **Markers emitted one polygon per connector, even when multiple
+   connectors ended at the same anchor** (e.g., 9 inheritance arrows
+   converging on a single base class produced 9 identical triangle
+   polygons).
+
+2. **Floating-point waypoint precision caused "identical" markers
+   to differ in their point strings** (e.g., `683.37 2041.37` vs
+   `683.39 2043.35`), defeating naive `body.uniq` deduplication.
+
+## Fix
+
+`Markers#layers` now deduplicates by **rounded anchor point** —
+the first coordinate pair of each polygon/path, rounded to integer.
+Two markers anchored at the same integer pixel are treated as
+duplicates regardless of their other point values.
+
+## Impact (full plateau measurement)
+
+| Metric | Before | After |
+|---|---|---|
+| Polygon delta vs ref | +442 (46% over) | -10 (parity) |

data/TODO.diagrams/03-ea-style-svg-emitter.md

@@ -0,0 +1,70 @@
+# 03 - EA-Style SVG Emitter
+
+## Status: DONE (2026-07-21) (depends on 02)
+
+## Problem
+
+The current `Ea::Svg::Renderer` emits minimal SVG: header,
+background rect, then per-element `<g class="element">` groups
+with the box + label inside. EA's SVG output is structurally
+different:
+
+1. DOCTYPE declaration (SVG 1.0)
+2. Root `<svg>` with `width="Xcm" height="Ycm"` and
+   `viewBox="0 0 W H"`
+3. `<title></title>` (empty)
+4. `<desc>Created with Enterprise Architect (Build: 1628) 2</desc>`
+5. Background `<g style="fill:#FFFFFF;..."><rect .../></g>`
+6. For each element, TWO `<g>` blocks:
+   a. Shape `<g>` with `style="...fill:COLOR;..."` containing the
+      `<rect>`
+   b. Text `<g>` with `style="fill:#000000;..."` containing all
+      `<text>` labels for that element
+7. Divider line as `<g><path d="M x y L x2 y2"/></g>`
+8. Connector paths as separate `<g>` blocks per path segment
+9. Arrow markers as `<g><polygon .../></g>`
+10. Connector labels as a final `<g>` block of `<text>`
+
+The output is layered by visual category, not by element. Our
+current emitter layers by element, mixing shapes and text in one
+`<g>`.
+
+## Approach
+
+Rewrite the emitter to follow EA's layering. Each render phase
+emits one or more `<g>` blocks in the canonical order:
+
+1. `Ea::Svg::EaEmitter::Background`
+2. `Ea::Svg::EaEmitter::Elements` (one shape `<g>` + one text `<g>`
+   per element, in z-order)
+3. `Ea::Svg::EaEmitter::Dividers` (one `<g>` per divider line)
+4. `Ea::Svg::EaEmitter::Connectors` (one `<g>` per path)
+5. `Ea::Svg::EaEmitter::Markers` (filled / open polygons)
+6. `Ea::Svg::EaEmitter::Labels` (all text labels last)
+
+Each emitter is a single-responsibility class. The orchestrator
+calls them in order.
+
+The existing `Ea::Svg::Renderer` stays as a thinner alternative
+(useful for diagrams without full style data, e.g. from QEA
+sources with sparse style). The new `EaEmitter` is the default
+when full EA-style data is available.
+
+## Files
+
+- `lib/ea/svg/ea_emitter.rb` (orchestrator)
+- `lib/ea/svg/ea_emitter/background.rb`
+- `lib/ea/svg/ea_emitter/elements.rb`
+- `lib/ea/svg/ea_emitter/dividers.rb`
+- `lib/ea/svg/ea_emitter/connectors.rb`
+- `lib/ea/svg/ea_emitter/markers.rb`
+- `lib/ea/svg/ea_emitter/labels.rb`
+- `lib/ea/svg/ea_emitter/canvas.rb` (computes cm dimensions + viewBox)
+- `spec/ea/svg/ea_emitter/*_spec.rb`
+
+## Verification
+
+- Byte-level structural diff against EA's reference SVG for one
+  diagram. We don't require pixel-perfect match (font rendering
+  differences), but the element layering, group structure, and
+  attribute presence should match.

data/TODO.diagrams/03-text-over-rendering.md

@@ -0,0 +1,30 @@
+# TODO-D 03 - Text over-rendering
+
+## Status: COMPLETE (2026-07-26)
+
+## Root cause
+
+The tagged values compartment was rendered unconditionally for
+every classifier that had tagged values, regardless of the
+diagram's actual display configuration. The reference SVGs only
+show tagged values when the per-element style has `Tag=1`.
+
+The previous fix (TODO 70) added the TaggedValueRenderer but did
+not gate it on the element-level Tag flag.
+
+## Fix
+
+`Elements#groups_for` now reads `element.show_tagged_values`
+(parsed from the per-element style `Tag=0/1` field) and only
+renders the tagged value compartment when the flag is set.
+
+The `DiagramElement` model gained `show_tagged_values` boolean.
+`ExtensionStyleParser` populates it from the `Tag=` style key.
+`DiagramBuilder` passes it through to the model.
+
+## Impact (full plateau measurement)
+
+| Metric | Before | After |
+|---|---|---|
+| Text delta vs ref | +5134 (29% over) | -252 (parity) |
+| Text overlap avg | 57% | 62% |

data/TODO.diagrams/04-connector-routing-from-soid-eoid.md

@@ -0,0 +1,55 @@
+# 04 - Connector Routing via SOID/EOID Resolution
+
+## Status: DONE (2026-07-21, folded into TODO 03)
+
+## Problem
+
+EA connector geometry stores only bend deltas (SX/SY/EX/EY) and
+the EDGE code (which side of the element the line attaches to).
+The actual line endpoints are computed by EA's renderer at draw
+time, by looking up the source and target element placements via
+their DUIDs (style `SOID` and `EOID`).
+
+Our current QEA adapter computes waypoints from the connector's
+Start_Object_ID/End_Object_ID via the model. That works but
+ignores the EDGE hint, producing lines that always start at the
+element center instead of the correct edge.
+
+## Approach
+
+In both the QEA and XMI source adapters, when building a
+DiagramConnector:
+
+1. Resolve source and target placements via SOID/EOID (XMI) or
+   Start_Object_ID/End_Object_ID (QEA).
+2. Read the `EDGE` field (1=top, 2=right, 3=bottom, 4=left,
+   5..8 = diagonal variants).
+3. Compute the source connection point as the center of the
+   chosen edge on the source element.
+4. Apply the SX/SY delta to get the first bend.
+5. Apply the EX/EY delta from the target edge center to get the
+   second bend.
+6. Compute the target connection point as the center of the
+   chosen edge on the target element.
+
+Emit exactly 2-4 waypoints: source edge → first bend → second
+bend → target edge. This matches EA's typical "L" or "Z" routing.
+
+For connectors without EDGE or SOID/EOID, fall back to straight
+line between element centers.
+
+## Files
+
+- `lib/ea/sources/qea/diagram_builder.rb`
+- `lib/ea/sources/xmi/diagram_builder.rb`
+- `lib/ea/svg/edge_anchor.rb` (computes edge center given bounds +
+  EDGE code)
+- `spec/ea/svg/edge_anchor_spec.rb`
+
+## Verification
+
+- Spec: source element with EDGE=1 produces a source point at the
+  top edge center.
+- Spec: connector with both bends produces 4 waypoints.
+- Visual: connector lines visually attach to element edges, not
+  centers.

data/TODO.diagrams/04-rect-under-rendering.md

@@ -0,0 +1,33 @@
+# TODO-D 04 - Rect under-rendering
+
+## Status: WONTFIX (data drift) (2026-07-26)
+
+## Investigation
+
+Across 185 plateau diagrams, we under-render 221 rects (11%). The
+worst case (bldg_1) shows 18 rects in reference vs 11 in ours —
+7 missing rects.
+
+Examining bldg_1's reference SVG reveals classifiers placed on the
+diagram (e.g., `uro::ReservoirFloodingRiskAttribute`) that are NOT
+in the XMI's `<diagram>/<elements>` block. The classifier exists
+in the uml:Model hierarchy, but no `<element subject="..."/>` ref
+places it on this diagram.
+
+## Conclusion
+
+The reference SVGs were generated from a MORE COMPLETE XMI than
+the one we have. The XMI/SVG pair has drift — the SVG has
+placements the XMI doesn't carry.
+
+This is a fixture data issue, not an emitter bug. We cannot render
+elements the XMI doesn't place. Closing this gap requires either:
+
+1. Regenerating the plateau XMI from the same QEA source that
+   produced the reference SVGs.
+2. Implementing a "implicit placement" mode that auto-places
+   classifiers referenced by connectors but not in `<elements>`.
+   This would be guesswork — we don't know where EA placed them.
+
+Option 1 is the right path. Marking this wontfix pending fixture
+regeneration.

data/TODO.diagrams/05-canvas-dimension-parity.md

@@ -0,0 +1,51 @@
+# TODO-D 05 - Canvas dimension parity
+
+## Status: PARTIAL (2026-07-26)
+
+## Current state
+
+| | Avg delta | Range |
+|---|---|---|
+| Width | +87px | -403 to +1482 |
+| Height | +576px | -109 to +4833 |
+
+For diagrams where XMI matches reference content (small delta),
+the canvas is consistently ~20-25 px wider and ~7-15 px taller
+than reference. That delta is the frame margin.
+
+## Frame margin rule
+
+Reference SVGs use non-uniform frame margins around element
+bounds:
+
+- Left:   35 px (body left to canvas left)
+- Right:  50 px (body right to canvas right)
+- Top:    60 px (body top to canvas top)
+- Bottom: 36 px (body bottom to canvas bottom)
+
+These come from EA's frame outer border (6 px from canvas edge)
+plus an additional 29/44/54/30 px inset for the body. The asymmetry
+exists because:
+
+- Top: extra space for the frame tab label (extends from y=6 to
+  y=26 plus padding to body_top=60).
+- Right/bottom: extra space for shadow / image padding.
+
+## Fix attempted
+
+`BoundsCalculator#compute` already reserves 20 px above each
+Package element for the tab polygon. Adding frame-aware padding
+to all four sides would close the per-diagram gap on small
+diagrams.
+
+## Why deferred
+
+The 576 px average height delta dwarfs the frame margin issue.
+Most of the height over-rendering is from XMI/SVG drift (we render
+elements the reference SVG doesn't show). Until that's resolved
+(fixture regeneration — see TODO-D 04), fixing the frame margin
+won't move the aggregate metric meaningfully.
+
+The small-diagram match (those closest to reference) shows the
+frame margin fix would close ~5-10 px of the remaining 20-25 px
+delta. Not enough to justify the added complexity right now.

data/TODO.diagrams/05-marker-rendering-per-relationship-type.md

@@ -0,0 +1,49 @@
+# 05 - Marker Rendering Per Relationship Type
+
+## Status: DONE (2026-07-21, folded into TODO 03)
+
+## Problem
+
+EA renders different arrow markers based on the connector's
+semantic type:
+
+- **Association** (navigable): filled triangle at target
+- **Generalization**: open triangle at target (white fill, black
+  stroke)
+- **Realization**: open triangle at target + dashed line
+- **Dependency**: open arrow at target + dashed line
+- **Aggregation** (source): open diamond at source
+- **Composition** (source): filled diamond at source
+
+Our current renderer emits a filled triangle at target regardless
+of relationship type, plus a diamond for aggregations. The
+distinction between open and filled markers matters visually.
+
+## Approach
+
+Add a `MarkerResolver` that maps a relationship type + end
+(source/target) to a marker shape:
+
+- `:filled_triangle`, `:open_triangle`, `:filled_diamond`,
+  `:open_diamond`, `:open_arrow`, `:none`
+
+Each shape is rendered as a 4-point `<polygon>` with the
+appropriate fill color.
+
+The marker anchor is the END of the polyline (target) or the
+START (source). The marker is rotated to align with the line's
+direction at that end.
+
+## Files
+
+- `lib/ea/svg/marker_resolver.rb`
+- `lib/ea/svg/marker_shapes.rb` (one class per shape)
+- Update `lib/ea/svg/ea_emitter/markers.rb`
+- `spec/ea/svg/marker_resolver_spec.rb`
+
+## Verification
+
+- Spec: Association → filled triangle at target.
+- Spec: Generalization → open triangle at target.
+- Spec: Composition → filled diamond at source + filled triangle
+  at target.

data/TODO.diagrams/06-connector-labels.md

@@ -0,0 +1,49 @@
+# 06 - Connector Labels (Role Names + Multiplicities)
+
+## Status: DONE (2026-07-21, folded into TODO 03)
+
+## Problem
+
+EA renders labels on connectors at four canonical positions:
+
+- `LLB` (lower-left, near source) — source role name
+- `LLT` (upper-left, near source) — source multiplicity
+- `LRB` (lower-right, near target) — target role name
+- `LRT` (upper-right, near target) — target multiplicity
+
+Each label has CX/CY (size), OX/OY (offset from the connector
+endpoint), plus font/style flags.
+
+Our current renderer emits no connector labels at all. The
+information is in the XMI geometry string but never extracted.
+
+## Approach
+
+Extend the XMI adapter's geometry parser to also extract the four
+label boxes, each as an `Ea::Model::LabelBox` with:
+
+- `role` (:source_name, :source_multiplicity, :target_name,
+  :target_multiplicity)
+- `text` (decoded from the model's relationship ends)
+- `offset_x`, `offset_y` (from OX/OY)
+- `width`, `height` (from CX/CY)
+
+The emitter renders each label as `<text>` at the appropriate
+offset from the connector endpoint.
+
+For QEA sources, the same data is in the connector's `SourceRole`
+and `DestRole` notes + cardinality fields.
+
+## Files
+
+- `lib/ea/model/label_box.rb`
+- `lib/ea/sources/xmi/extension_geometry_parser.rb` (extend)
+- `lib/ea/svg/ea_emitter/labels.rb` (extend)
+- `spec/ea/sources/xmi/extension_geometry_parser_spec.rb`
+- `spec/ea/svg/ea_emitter/labels_spec.rb`
+
+## Verification
+
+- Spec: known geometry string yields 4 label boxes with correct
+  offsets.
+- Visual: connector labels appear at the same positions as EA.

data/TODO.diagrams/06-group-layering-parity.md

@@ -0,0 +1,39 @@
+# TODO-D 06 - Group layering parity
+
+## Status: PARTIAL (2026-07-26)
+
+## Current state
+
+EA emits each `<rect>`, `<polygon>`, `<path>`, `<text>` inside its
+own `<g>` block with a specific `style` attribute. Style strings
+differ by:
+
+- stroke_width (1 vs 2)
+- stroke_linecap (round vs square)
+- stroke_linejoin (bevel vs miter)
+- fill color
+- stroke color
+- opacity
+
+Our emitter groups output by `style_key` (a Symbol like
+`:diamond_filled` or `:triangle_open`), with the style string
+looked up from a small dispatch table. This matches EA's grouping
+semantics for most cases.
+
+## Note element body
+
+The Note element body was previously emitted as a `<polygon>`. EA
+emits it as a closed `<path d="M...L...Z"/>` with
+`stroke-linejoin=bevel` and `stroke-linecap=square`. Fixed in
+commit f4fa55f.
+
+## Remaining gap
+
+EA sometimes uses different `stroke-linecap` for the same shape
+type depending on whether it's a "decorative" element (square cap)
+or a "connector" element (round cap). Our style dispatch table
+doesn't distinguish these. Visible in:
+
+- Note bodies (square) vs classifier rects (round) — fixed
+- Connector lines (round) vs divider lines (round) — both round
+- Visibility icon rects inside attribute compartments — TBD

data/TODO.diagrams/07-canvas-size-and-viewbox.md

@@ -0,0 +1,39 @@
+# 07 - Canvas Size + viewBox Computation
+
+## Status: DONE (2026-07-21, folded into TODO 03)
+
+## Problem
+
+EA's root `<svg>` element declares `width="Xcm" height="Ycm"` and
+`viewBox="0 0 W H"`. The cm dimensions are computed from the
+union of all element `image_bounds` (the padded bounds), with
+~25 px padding around the canvas. The viewBox is in pixel units.
+
+Our current renderer computes a viewBox from the union of element
+bounds + connectors, but doesn't emit cm dimensions.
+
+## Approach
+
+`Ea::Svg::EaEmitter::Canvas` computes:
+
+1. Union of all element `image_bounds` (NOT logical bounds — EA's
+   canvas size is based on the visual padding).
+2. Adds 10 px outer margin.
+3. Emits viewBox = "min_x min_y width height".
+4. Emits width/height in cm as `width / 28.346` (72 DPI conversion).
+
+The canvas module is also responsible for translating the
+coordinate space if min_x/min_y are non-zero (EA's convention is
+to keep the viewBox starting at 0,0 by translating all elements).
+
+## Files
+
+- `lib/ea/svg/ea_emitter/canvas.rb`
+- `spec/ea/svg/ea_emitter/canvas_spec.rb`
+
+## Verification
+
+- Spec: known element set produces expected viewBox and cm
+  dimensions.
+- Visual: SVG opens in a viewer at the same physical size as EA's
+  output.

data/TODO.diagrams/07-text-content-fidelity.md

@@ -0,0 +1,65 @@
+# TODO-D 07 - Full text content fidelity
+
+## Status: PARTIAL (62% overlap) (2026-07-26)
+
+## Current state
+
+Text overlap (Jaccard index of text content sets between our SVG
+and reference SVG):
+
+- Average across 185 plateau diagrams: **62%**
+- Best diagrams: ~95%
+- Worst diagrams: ~20%
+
+## What's working
+
+- Classifier names and stereotypes render correctly when the
+  element is placed on the diagram.
+- Attribute text matches when the element has Tag=0 (no tagged
+  values compartment).
+- Visibility prefixes ("+ ", "- ") match.
+- Multiplicity brackets match.
+
+## What's still off
+
+### 1. Tagged value visibility (mostly fixed, edge cases remain)
+Reference SVGs don't render the "tags" header compartment except
+on 2 diagrams. Our Tag-flag gating brought text overlap from 41%
+to 62%. Remaining misses are likely from elements where the
+`Tag=1` flag is set but the reference still doesn't render tags
+— possibly tied to stereotype source (profile-applied vs
+user-defined tagged values).
+
+### 2. Qualified name vs simple name
+Reference uses qualified names like
+`uro::TrafficVolumeAttribute`. Our output sometimes uses the
+short name only. The qualified_name attribute is set on the
+Classifier model, but the renderer doesn't always pick it up
+correctly when the element is placed on a sub-package diagram.
+
+### 3. Attribute ordering
+Within a classifier's attribute compartment, EA sorts attributes
+by some criteria (possibly visibility then alphabetical). Our
+ordering follows the XMI's `ownedAttribute` order, which may
+differ.
+
+### 4. Attribute visibility color
+Reference uses different fill colors for public/protected/private
+attributes (`#66413F` for some, `#595959` for others). Our
+renderer uses a single text color from the theme.
+
+## Path to 100% text overlap
+
+1. Characterize the tagged value visibility rule by examining
+   which elements with `Tag=1` still don't render tags in
+   reference (estimated 5-10 diagrams).
+
+2. Always use `classifier.qualified_name` for the header label
+   (currently mixed).
+
+3. Sort attributes by visibility prefix, then alphabetical.
+
+4. Apply theme.color_for_attribute_visibility for attribute text.
+
+Each of these is a separate fix. None require architectural
+changes.