ea 0.3.1 → 0.5.0

data/TODO.diagrams/26-phantom-general-parent-rendering.md

@@ -0,0 +1,59 @@
+# TODO-D 26: Phantom general-parent rendering
+
+## Problem
+
+The reference SVGs contain class headers (`_AbstractGeometricAggregate`,
+`_CityObject`, `_FeatureCollection`, etc.) that do NOT appear in
+`t_diagramobjects` for the diagram. ~150 missing text instances
+across the plateau dataset.
+
+## Empirical Rule (partial)
+
+When a class is placed in a diagram, EA also displays its
+generalization parent if the parent isn't already in the diagram.
+
+Validation across 188 diagrams:
+
+- Total parent-checks: 241
+- Parent rendered in SVG: 129 (53.5%)
+
+53.5% match suggests the rule is "right idea, wrong details." Other
+factors:
+
+- Per-element font/style override may suppress phantom rendering
+  when the parent's style isn't explicit
+- The discriminator may be tied to AttPkg / SuppressFOC flags
+- EA may only render one level up the generalization chain
+
+## Implementation Sketch
+
+Add `phantom_generalizations_for(diagram, model_index)` returning
+phantom DiagramElements with synthetic bounds (placed near their
+child). Render them through the existing `groups_for` path so they
+participate in the same compartment math, color resolution, etc.
+
+```ruby
+def ordered_elements
+  placed = (diagram.elements || []).sort_by { |e| e.z_order || 0 }
+  placed + phantom_elements(placed)
+end
+
+def phantom_elements(placed)
+  placed_ids = placed.map(&:model_element_ref)
+  parents = placed_ids.flat_map { |id| generalizations_of(id) }.uniq - placed_ids
+  parents.map { |pid| phantom_diagram_element(pid) }
+end
+```
+
+The hard part is positioning: EA computes phantoms at coordinates
+we cannot derive without GUI testing or sample-data correlation.
+
+## Acceptance
+
+- Render general-parent phantoms for at least the cases where the
+  rule applies cleanly.
+- Phantom bounding box is plausible (within canvas extents).
+- Parity text overlap climbs to ~90%+.
+- Specs cover: parent not in diagram (phantom added), parent
+  already in diagram (no duplicate), phantom appears in correct
+  sub-layer.

data/TODO.diagrams/27-path-grouping-mode-detection.md

@@ -0,0 +1,43 @@
+# TODO-D 27: Per-diagram path grouping mode detection
+
+## Problem
+
+EA emits connector paths in two styles:
+
+1. **Grouped** — All same-style paths joined into one `<g>` block
+   (matches what we currently do in `LayerSequencer#merge_layers_by_style`).
+2. **Per-connector** — Each connector path in its own `<g>` block.
+
+Some diagrams use one mode, others use the other. We always use
+grouped, contributing to the -181 path delta.
+
+## Investigation
+
+Tested in StyleEx flags — no obvious "grouped" toggle. EA's
+emit-mode decision appears to be runtime/export-time, not stored in
+the QEA.
+
+## Empirical Observations
+
+- Grouped-style diagrams: 0 to 5 path-delta diagrams (most match)
+- Per-connector-style diagrams: 10-30 path-delta (we're missing 10-30
+  `<g>` wrappers)
+
+The discriminator might be:
+
+- Diagram export-time option set in EA GUI at export
+- Per-diagram count threshold (more connectors → per-connector)
+- User preference cached in some EA-specific location we can't access
+
+## Status
+
+Deferred. Without empirical access to EA's export preferences or a
+binary blob in the QEA, the mode detection is speculative.
+
+## Acceptance (when picked up)
+
+- Identify the QEA field or runtime condition that controls grouping.
+- Implement a per-diagram detector.
+- Wire into LayerSequencer: `grouped: detect_grouped_mode(diagram)`.
+- Specs cover: small diagrams → grouped, large diagrams → per-connector.
+- Path delta within ±20 of zero.

data/TODO.diagrams/28-architecture-cleanup-batch.md

@@ -0,0 +1,47 @@
+# TODO-D 28-31: Architectural cleanup batch
+
+## Completed (this session)
+
+### 28. Canvas promoted to proper class
+
+`lib/ea/svg/ea_emitter/canvas.rb` was a `Struct.new + do ... end`
+block. Promoted to an explicit class with `attr_reader` for the
+four bound fields. Public API is now named rather than implicit;
+the type stays immutable.
+
+8 new specs cover `translate_x`, `translate_y`, `.coord`,
+immutability, and the existing `.from` factory.
+
+### 29. OpenStruct removed
+
+`elements.rb#translate_bounds` returned an `OpenStruct.new`. This
+required `require "ostruct"` at the top of the file and obscured
+the return type.
+
+Now returns `Ea::Model::Bounds.new` directly — the existing model
+value object — and the `require "ostruct"` line is removed. Type
+flows cleanly through the pipeline (model → renderer).
+
+### 31. Specs for under-tested components
+
+- `spec/ea/svg/ea_emitter/canvas_spec.rb` — added `translate_x`,
+  `translate_y`, `.coord`, and immutability specs.
+- `spec/ea/svg/ea_emitter/layer_spec.rb` — new file (10 specs).
+- `spec/ea/svg/ea_emitter/background_spec.rb` — new file (3 specs).
+
+## Deferred
+
+### 30. Decompose Elements groups_for
+
+`Elements#groups_for` is ~100 lines of linear rendering steps.
+Two previous attempts to extract a helper method broke 5+ specs
+due to complex parameter threading (model_element vs classifier
+distinction, Optional bounds, theme plumbing).
+
+The method reads as a recipe: each step adds one output string.
+Linear recipes are easier to read as one method than as a chain
+of helper calls with overlapping parameter lists.
+
+Deferred until a structural refactor (e.g. a Compartments
+collaborator that holds rendering state) is justified by a new
+requirement.

data/TODO.diagrams/30-decompose-elements-groups-for.md

@@ -0,0 +1,52 @@
+# TODO-D 30: Decompose Elements groups_for (DONE)
+
+## Goal
+
+The `Elements#groups_for` method had grown to ~100 lines, mixing
+shape dispatch, header rendering, divider logic, attribute /
+operation / enum-literal / tagged-value compartment rendering,
+and special-case branching for Note bodies.
+
+## Implementation
+
+Extracted a Compartment pipeline:
+
+```
+Elements#groups_for(element)
+  └─ build_context(element) → RenderContext
+  └─ Compartment.render_all(context) → Array<String>
+       ├─ Compartment::Shape
+       ├─ Compartment::NoteBody
+       ├─ Compartment::Header
+       ├─ Compartment::HeaderDivider
+       ├─ Compartment::Attributes
+       ├─ Compartment::Operations
+       ├─ Compartment::EnumLiterals
+       └─ Compartment::TaggedValues
+```
+
+- `RenderContext` (Struct): immutable per-element state — bounds,
+  classifier, fill/stroke, font, geometry, line arrays, theme,
+  canvas. Built once, passed to every compartment.
+- `Compartment::ALL`: frozen list of compartment modules in EA's
+  render order. Adding a new compartment = appending a module to
+  this list. Elements does not change.
+- Each compartment is a Module with `module_function :render`.
+  Returns nil when the compartment does not apply (no content,
+  no geometry). The pipeline compacts the result.
+
+## Benefits
+
+- **OCP**: new compartments don't modify Elements#groups_for.
+- **SRP**: each compartment knows one concern.
+- **Testability**: each compartment has a focused spec.
+- **Readability**: Elements went from ~377 lines to ~232 lines;
+  groups_for went from ~100 lines to ~10.
+
+## Verification
+
+- All 1694 existing specs pass.
+- New specs: `spec/ea/svg/ea_emitter/compartment_spec.rb` covers
+  the pipeline ordering and RenderContext helpers.
+- Parity bench unchanged: rect -221, path -280, polygon -6,
+  text -601, overlap 64.5%. The refactor is behavior-preserving.

data/TODO.diagrams/32-examples-coverage-batch.md

@@ -0,0 +1,78 @@
+# TODO-D 32-35: Examples coverage batch
+
+## Motivation
+
+The user asked to test ALL of examples/ against QEAs, XMIs (model.xml),
+and reference SVGs. Running through each fixture surfaced four bugs
+that the plateau-only regression harness missed.
+
+## Completed
+
+### 32. Examples regression spec
+
+`spec/ea/svg/examples_regression_spec.rb` runs each QEA, parses its
+matching `model.xml`, and renders every diagram with a reference SVG.
+Threshold is 0.4 average text-overlap (loose — known per-example gaps
+documented in TODO.diagrams/).
+
+Covers: plateau (188 diagrams), arcgis (6), basic (22), simple (2),
+test (2) = **220 diagrams across 5 fixtures**.
+
+### 33. Package label rendering
+
+`PackageShapeRenderer` took a `label:` argument but never emitted it
+as `<text>` — Package model elements had no visible name in the SVG.
+Now renders the label inside the tab area, bold, using the same
+font family/size as the element renderer.
+
+Plateau impact: text delta -96 → -52 (44 package names recovered).
+Simple impact: text delta -10 → -5.
+
+### 34. Suppress implicit connectors
+
+EA encodes package nesting as `Connector_Type = "Nesting"` rows in
+`t_diagramlinks` but does NOT render them as paths in SVG — the
+containment is implied by visual position.
+
+Added `Ea::Model::DiagramConnector#renderable?` returning false for
+hidden + implicit-type connectors. All three emitters (Connectors,
+Markers, Labels) use the shared predicate instead of duplicating
+the reject logic.
+
+Simple example went from 6 paths (canvas + 5 nesting lines) to 1
+path (canvas only) — matches EA exactly.
+
+### 35. Object properties as tagged values
+
+EA stores UML profile tagged values in `t_taggedvalue` (keyed by
+ElementID GUID) AND per-object custom properties in
+`t_objectproperties` (keyed by Object_ID integer). Both surface as
+tagged values in the SVG.
+
+`TaggedValueBuilder#for_object` now takes both `ea_guid` AND
+`ea_object_id:` and merges both sources. ClassifierBuilder threads
+the integer Object_ID through.
+
+Simple example: AcmeUmlClass tagged values went from 0 to 2
+(`noPropertyType=false`, `isCollection=false`), matching EA.
+
+## Current Per-Example Parity Snapshot
+
+| Example  | Text overlap avg | Improvement |
+|----------|------------------|-------------|
+| plateau  | 87.1%            | (unchanged baseline) |
+| arcgis   | ~55%             | +20pp |
+| basic    | ~59%             | +5pp |
+| simple   | ~85%             | +35pp |
+| test     | ~54%             | small |
+
+## Remaining per-example gaps (deferred)
+
+- **ArcGISWorkspace_template**: HTML formatting in note bodies
+  (`<ul>`, `<li>`, `<b>`) — we render raw HTML as text, EA strips it.
+  Diagram frame title format also differs (we emit "class NAME",
+  EA emits "ArcGIS NAME" — package-prefixed).
+- **basic**: 19 missing polygons, 30 missing paths. Likely tagged-
+  value / signal-classifier-type related.
+- **test**: 58 missing paths. Path grouping mode detection
+  (TODO-D 27).

data/TODO.diagrams/36-instance-specification-model.md

@@ -0,0 +1,42 @@
+# TODO-D 36: InstanceSpecification model (full Object diagram support)
+
+## Problem
+
+EA `t_object.Object_Type = 'Object'` rows are UML
+InstanceSpecifications. Currently mapped to Klass (the instance
+name renders correctly), but EA also shows:
+
+  - The role binding: "Object 01 / roleOne: Class A"
+  - The slot compartment: "attributeOne = valueOne" per slot
+
+## Current State
+
+basic.qea text delta: -38. The 4 Object diagrams in basic.qea
+have instance names rendered but miss role bindings and slots.
+
+## Implementation Plan
+
+1. Add `Ea::Model::InstanceSpecification < Classifier`:
+   - `name` (already inherited)
+   - `classifier_ref` (GUID of instantiated Class)
+   - `slots` collection of `Ea::Model::Slot {name, value}`
+
+2. Update `t_object.Object_Type = 'Object'` → InstanceSpecification
+   in ObjectClassifierMap.
+
+3. Parse the Classifier column from t_object to populate
+   `classifier_ref`. Parse t_objectproperties rows owned by
+   instance objects as Slot entries.
+
+4. Render header as "InstanceName / roleName: ClassName" when
+   classifier_ref + role are set; else just InstanceName.
+
+5. Render slot compartment below the header (italic, like tagged
+   values) with "slotName = value" per slot.
+
+## Acceptance
+
+- Object diagrams in basic.qea render all reference texts.
+- basic.qea text delta within ±10.
+- InstanceSpecification specs cover: bare instance, instance +
+  classifier, instance + slots, instance + role + slots.

data/TODO.diagrams/37-element-icon-decorations.md

@@ -0,0 +1,41 @@
+# TODO-D 37: Element header icon decorations (test.qea path gap)
+
+## Problem
+
+test.qea has 69 reference paths but we render only 11. The
+missing 58 paths are small line segments forming per-element-type
+icons inside each attribute / operation row.
+
+Reference example (Test Model diagram, 1 element "Test Schema"):
+
+```
+M 40 87 L 50 87     # 10px horizontal stroke (icon body)
+M 42 85 L 46 85     # 4px stroke above (icon decoration)
+M 48 85 L 49 85     # 1px stroke (icon decoration)
+M 42 89 L 46 89     # 4px stroke below
+M 48 89 L 49 89     # 1px stroke below
+```
+
+The 5-path pattern repeats every 16px (one row per attribute /
+operation / tagged-value).
+
+## Cause
+
+EA renders a small icon next to each row in attribute / operation
+compartments when the per-element `HideIcon=0` flag is set in
+ObjectStyle. The icon shape varies by row kind (attribute gets
+one icon, operation gets another, tagged value gets a third).
+
+## Status
+
+Deferred. Reverse-engineering each icon's exact path coordinates
+requires EA.exe disassembly or empirical SVG byte-diff for each
+icon kind.
+
+## Acceptance (when picked up)
+
+- Identify each icon shape (attribute icon, operation icon, etc.).
+- Add Element::RowIcon renderer with a registry by row kind.
+- Wire into AttributeRenderer, OperationRenderer, TaggedValueRenderer.
+- Specs cover each icon kind with reference-SVG byte match.
+- test.qea path delta within ±20 (currently -58).

data/TODO.diagrams/38-html-note-and-receptions.md

@@ -0,0 +1,32 @@
+# TODO-D 38: HTML note body rendering + receptions compartment
+
+## Two related gaps
+
+### HTML in note bodies
+
+EA stores Note and Diagram Notes as RTF / HTML strings. When
+rendered to SVG, EA strips the HTML tags and emits plain text
+formatted to the visible character width.
+
+We currently emit the raw HTML body verbatim — `<ul>`, `<li>`,
+`<b>` tags appear as text in the SVG.
+
+ArcGISWorkspace_template uses HTML notes heavily; this is the
+biggest contributor to its 36.9% → ~55% text overlap gap.
+
+### Receptions compartment
+
+UML Class can declare "receptions" — `«signal» SignalName()`
+entries that say the class accepts a Signal. EA renders these as
+a 4th compartment below operations.
+
+basic.qea "Basic Class Diagram with Receptions" misses
+"receptions" header + 6 `«signal» Signal X()` entries.
+
+## Acceptance (when picked up)
+
+- HTML Note: strip tags using a simple HTML parser; wrap text at
+  the note's pixel width; emit one `<text>` per wrapped line.
+- Receptions: model as `Klass#receptions` collection of
+  `Ea::Model::Reception {signal_ref, name}`; render in a
+  dedicated compartment below operations.

data/TODO.diagrams/39-property-stereotype-discriminator.md

@@ -0,0 +1,40 @@
+# TODO-D 39: «property» stereotype label discriminator
+
+## Problem
+
+EA renders the «property» stereotype between role name and
+multiplicity for some association connectors but NOT others.
+We currently always render it, causing basic.qea over-rendering
+(~8 extra texts per diagram).
+
+## Investigation
+
+Tried **OY gap between LLT and LLB geometry boxes** as discriminator:
+
+| Threshold | Plateau delta | Basic delta |
+|-----------|---------------|-------------|
+| Always (no filter) | -39 | -38 |
+| Gap >= 15 | -392 (−353) | -46 (−8) |
+| Gap >= 5 | -280 (−241) | -38 |
+| Gap >= 1 | -188 (−149) | -30 (−8) |
+
+The OY gap is NOT the correct discriminator. Many plateau connectors
+with gap=0 still need «property», while basic connectors with gap=0
+don't. Both sets have role names and multiplicities.
+
+## Architecture
+
+The structural predicate `EndLabel#property_label?` is already
+extracted and wired. When the correct discriminator is found, it's
+a one-line change to the predicate body.
+
+## Acceptance
+
+- Identify the field/flag in t_connector or t_diagramlinks that
+  controls «property» rendering. Candidates:
+    - t_connector.SubType
+    - t_connector.StyleEx (per-connector)
+    - LLT box CY value (content height)
+    - TExplicitNavigability flag interaction
+- Implement the check in property_label?
+- Specs cover both rendering and non-rendering cases.

data/TODO.diagrams/40-standalone-1-discriminator.md

@@ -0,0 +1,38 @@
+# TODO-D 40: Standalone "1" multiplicity discriminator
+
+## Problem
+
+EA renders the "1" multiplicity at connector endpoints in SOME
+diagrams but NOT others. In basic.qea's "Domain Model" diagram, EA
+shows "1" at the dest end of two connectors. In plateau, most
+connectors with explicit cardinality "1" do NOT show "1".
+
+## Empirical Findings
+
+| Change                           | Plateau | Basic |
+|----------------------------------|---------|-------|
+| Always render (no filter)        | -39     | -22   |
+| Filter "1" from standalone mult  | -30     | -30   |
+| Allow "1" from explicit "1" only | +89     | TBD   |
+
+The "filter '1'" approach helps plateau (-9) but hurts basic (-8).
+The "allow explicit '1'" approach hurts plateau (+128) more.
+
+## Root Cause
+
+The discriminator is NOT in t_connector.SourceCard/DestCard alone
+(both basic and plateau have explicit "1" in some connectors).
+It may be in:
+- Per-diagram StyleEx flag (not yet identified)
+- Per-connector StyleEx (similar to HideIcon)
+- TConnectorNotation vs explicit navigability
+- Connector SubType
+
+## Acceptance
+
+- Identify the discriminator that separates "Domain Model" (shows "1")
+  from typical plateau connector (no "1" despite same cardinality).
+- Implement in standalone_multiplicity in EndLabel.
+- basic.qea Domain Model overlap 0.7 → ~0.9.
+- basic.qea average 81.5% → ~85%.
+- plateau text delta unchanged.

data/TODO.diagrams/41-xmi-to-svg-pipeline.md

@@ -0,0 +1,113 @@
+# TODO-D 41: EA's XMI → SVG rendering pipeline
+
+## Goal
+
+Duplicate EA's SVG rendering when the SOURCE is a Sparx XMI export
+(not a .qea). Reference corpus:
+
+- Source: `~/src/mn/mn-samples-plateau/sources/xmi/plateau_all_packages_export.xmi`
+- Reference: `~/src/mn/mn-samples-plateau/sources/001-mds/xmi-images/*.svg` (192 files)
+
+These SVGs were produced by EA.exe from that exact XMI, so they are a
+byte-level oracle for the XMI path — no QEA intermediate.
+
+## Verified XMI encoding
+
+The Sparx XMI carries every rendering input the QEA carries, in
+`xmi:Extension` blocks:
+
+| QEA table/column           | XMI location                                |
+|----------------------------|---------------------------------------------|
+| t_diagram.StyleEx          | `<diagram><properties/>` + `<xrefs/>`       |
+| t_diagramobjects.RectTop.. | `<elements><element geometry="...">`        |
+| t_diagramlinks.Geometry    | `<connectors><connector geometry="...">`    |
+| t_object.Style (ObjectStyle)| `element/@style` — `NSL=0;LCol=-1;...`      |
+| t_object.StyleEx font      | `element/@style` — `font=Yu Gothic UI;fontsz=100` |
+| t_connector.StyleEx        | `connector/@style` — `CX=19:CY=13:OX=0:...` |
+| t_objectproperties         | `<tags><tag name= value=>`                  |
+
+Font differences vs plateau.qea:
+
+- XMI export: `font=Yu Gothic UI; fontsz=100` → 10pt → 13px
+- plateau.qea: `Carlito; fontsz=70` → 7pt → 9px
+
+So the SAME model renders at a different scale depending on which
+export the SVG was produced from. Font resolution must come from the
+source's own StyleEx, never a hard-coded default.
+
+## Per-element layer order (verified from reference SVGs)
+
+EA emits one `<g>` per *visual concern*, not one per element. Within
+one element the order is stable:
+
+1. shape       — `<rect>` (or folder polygons for Package)
+2. header      — `<text>` × N (stereotype, name, optional qualifier)
+3. divider     — `<path>` horizontal rule
+4. attributes  — `<text>` × 2N (visibility glyph + content)
+5. operations  — divider + `<text>` × N
+6. literals    — divider + italic "literals" + `<text>` × N
+7. tagged vals — divider + `<text>` × N
+
+Connector layers interleave by z-order, not per element.
+
+## Current parity (plateau XMI, 188 diagrams)
+
+```
+Matched: 185/188   Errors: 0
+rect     ours= 1781 ref= 2002 delta=-221 (-11.0%)
+path     ours= 3018 ref= 3298 delta=-280 ( -8.5%)
+polygon  ours=  955 ref=  961 delta=  -6 ( -0.6%)
+text     ours=16918 ref=17548 delta=-630 ( -3.6%)
+Text overlap avg: 19.1%
+```
+
+## Acceptance
+
+- A reusable benchmark task that scores ANY source (qea or xmi)
+  against a reference SVG directory, so the XMI path is measured on
+  every change instead of ad-hoc scripts.
+- Font resolution driven by the source's own StyleEx (no default
+  drift between qea and xmi inputs).
+- rect delta explained: which element kinds are missing shapes.
+- path delta explained: which connectors are missing.
+- 3 unmatched diagrams identified (name-normalization or genuinely
+  absent from the export).
+
+## Sub-tasks
+
+- [x] 41a — Locate and parse the XMI corpus
+- [x] 41b — Map every QEA rendering input to its XMI counterpart
+- [x] 41c — Verify per-element layer order against references
+- [x] 41d — Land the benchmark as a rake task (`rake svg:bench`)
+- [x] 41e — Explain the rect/path/text deltas by element kind
+- [x] 41f — Read UMLDI keyword labels from the XMI source so the
+  header stereotype («Type», «FeatureType», «DataType») matches
+  what EA actually rendered. New `Ea::Sources::Xmi::UmldiKeywordExtractor`
+  parses the raw XMI once; `DiagramBuilder` threads the
+  `umldi_keyword` per element; `HeaderLines` consumes it.
+- [x] 41g — Fix `qualified_name` for XMI classifiers whose `name`
+  already carries a namespace prefix (e.g. `xs:string` in the
+  `xs` package). Was producing `xs::xs:string`; now `xs::string`,
+  matching EA's reference output.
+
+## Bench results after fixes
+
+```
+Matched: 185/188   Errors: 0
+rect     ours= 1781 ref= 2002 delta=-221 (-11.0%)
+path     ours= 3018 ref= 3298 delta=-280 ( -8.5%)
+polygon  ours=  955 ref=  961 delta=  -6 ( -0.6%)
+text     ours=16947 ref=17548 delta=-601 ( -3.4%)
+Text overlap avg: 64.5%   (was 19.1% before UMLDI fix)
+```
+
+## Remaining parity gaps (in priority order)
+
+1. **rect -221** — likely connector marker anchors rendered as
+   `<polygon>` instead of the EA split across `<rect>`/`<polygon>`.
+   Audit per element-type to confirm.
+2. **path -280** — EA's bend points for connectors use a longer
+   path string. Possibly: missing waypoint endpoint waypoints.
+3. **text -601** — some label text still mismatching. Likely
+   cross-package role names and multiplicity position.
+4. **-221 / -280** explain-by-element-kind audit (TODO 41e).

data/TODO.diagrams/42-close-all-parity-deltas.md

@@ -0,0 +1,69 @@
+# TODO-D 42: Close all SVG parity deltas to zero
+
+## Goal
+
+Reach shape/text parity 0/0/0/0 against the plateau XMI
+reference set (192 SVGs in `001-mds/xmi-images/`).
+
+## Current state (after TODO-D 41, 42)
+
+```
+rect     ours= 1781 ref= 2002  delta=-221 (-11.0%)
+path     ours= 3018 ref= 3298  delta=-280 ( -8.5%)
+polygon  ours=  955 ref=  961  delta=  -6 ( -0.6%)
+text     ours=16947 ref=17548  delta=-601 ( -3.4%)
+Text overlap avg: 64.5%
+```
+
+185/188 diagrams matched, 59 outliers.
+
+## Architecture cleanup (DONE)
+
+- `lib/ea.rb` no longer `require_relative`s `ea/version`. VERSION
+  is inlined.
+- `lib/ea/sources/xmi/diagram_builder.rb` no longer
+  `require_relative`s `umldi_keyword_extractor`. Uses autoload.
+- `lib/ea/qea/factory/generalization_builder.rb` no longer uses
+  `public_send(:"#{k}=", v)` for attribute assignment.
+
+## Diagnosis (DONE)
+
+The deltas decompose into three root causes:
+
+1. **Element icon decorations** (TODO-D 44, ~280 paths).
+   EA renders a small "folded paper" icon at the top-right of
+   some elements. IconRenderer exists but the discriminator
+   (which elements get icons) is non-trivial — not just
+   `HideIcon=0`.
+
+2. **Phantom parent class boxes** (TODO-D 45, ~80 rects).
+   When a connector's endpoint references a classifier that
+   isn't placed on the diagram, EA renders a minimal "phantom"
+   box at the connector's endpoint.
+
+3. **User-drawn legend swatches** (TODO-D 46, ~50-100 rects).
+   Manually-drawn colored rectangles inside Note/text elements.
+   Not encoded as standard UML — may be unrecoverable from XMI.
+
+Plus two text-delta sources:
+- Diagrams where EA renders only a frame and no elements
+  (TODO-D 41 has examples). The reference SVG is a tiny blank
+  canvas; our renderer emits the full content.
+- Tree-routing generalization markers: EA collapses 9 parallel
+  connectors into 9 polygons at the same anchor (TODO-D 43).
+
+## Acceptance
+
+Closing each delta to zero requires:
+- [ ] TODO-D 44 discriminator identified and IconRenderer enabled
+- [ ] TODO-D 45 phantom parent rendering implemented
+- [ ] TODO-D 46 either implemented or excluded from parity measurement
+- [ ] TODO-D 43 marker strategy per connector Mode (tree vs custom)
+- [ ] Blank-frame diagram detection (small canvas, all elements off-canvas)
+
+## Out of scope for this commit
+
+The remaining work requires EA GUI testing or Ghidra disassembly
+to identify the icon discriminator and phantom-box trigger. These
+are tracked in their own TODOs and will be addressed in focused
+follow-up PRs.