ea 0.4.0 → 0.5.1

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.

data/TODO.diagrams/43-marker-deduplication-strategy.md

@@ -0,0 +1,54 @@
+# TODO-D 43: Marker deduplication strategy
+
+## Current behavior
+
+`lib/ea/svg/ea_emitter/markers.rb` deduplicates marker polygons/paths
+by their anchor point (first coord pair, rounded to integer).
+
+```
+unique_bodies = grouped_entries.uniq { |e| anchor_key(e.body) }
+```
+
+## Reference behavior (verified from plateau)
+
+EA's reference set is INCONSISTENT:
+
+- `EAID_E7AABA98` (Building): 9 parallel generalizations to one
+  parent — EA emits 9 polygons at the same anchor (collapses NOT
+  applied).
+- `EAID_9994BF62` (地域地区および用途地域): 29 generalizations, EA
+  emits only 3 triangles. Many generalizations share the same
+  parent — EA emits ONE marker per parent point, not per connector.
+
+So:
+- Same parent, single shape per connector endpoint: 1 marker (collapsed)
+- Same parent, parallel (multiple distinct routes): 1 marker per route
+
+## Discriminator hypothesis
+
+The discriminator is likely the connector's `Mode` style flag:
+
+- `Mode=1` — Custom routing (each connector has its own route →
+  emit per connector)
+- `Mode=3` — Tree routing (children share route to parent →
+  emit ONE marker per parent point)
+
+## Acceptance
+
+- Identify the exact field that distinguishes "tree" from "custom"
+  routing.
+- Implement per-mode marker strategy:
+  - Tree mode: emit one marker per (parent, edge) tuple.
+  - Custom mode: emit one marker per connector.
+- Bench polygon delta → 0.
+- Spec coverage for both modes.
+
+## Bench impact (current)
+
+```
+polygon  ours=955 ref=961 delta=-6  (-0.6%)
+```
+
+If the discriminator is wrong we either over-render (Mode=3 case
+with parallel connectors) or under-render (Mode=1 case with shared
+parent).

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

@@ -0,0 +1,34 @@
+# TODO-D 44: Element icon decorations (folded-paper class icon)
+
+## Symptom
+
+EA renders a small "folded paper" icon at the top-right corner of
+each class shape. The icon is two `<path>` elements:
+
+1. Outer outline: `M x y L x+6 y L x+9 y+4 L x+9 y+11 L x y+11 Z`
+2. Folded corner: `M x+6 y L x+6 y+4 L x+9 y+4`
+
+Style:
+- `stroke-width:1; stroke-linecap:square; stroke-linejoin:bevel;`
+- Outer: `fill:#DCF8F0; stroke:#577AC1` (light cyan fill, blue stroke)
+- Inner corner: `fill:transparent; stroke:#577AC1`
+
+## Discriminator
+
+The XMI element style carries `HideIcon=0` (show) or `HideIcon=1`
+(hide). When shown, EA emits the icon paths regardless of element
+type (class, data type, etc.).
+
+## Bench impact (estimated)
+
+- 2 paths per shown icon × ~140 elements with `HideIcon=0` ≈ 280
+  paths. This matches the current path delta of `-280`.
+
+## Acceptance
+
+- Add an `Element::IconRenderer` that emits the two `<path>`
+  elements at (bounds.right - 12, bounds.top + 3) when
+  `element.style["HideIcon"] == "0"` (default visible).
+- Thread HideIcon parsing through `ExtensionStyleParser`.
+- Spec coverage for both shown and hidden cases.
+- Bench path delta → 0.

data/TODO.diagrams/45-phantom-parent-class-boxes.md

@@ -0,0 +1,40 @@
+# TODO-D 45: Phantom parent class boxes (generalization tree)
+
+## Symptom
+
+Some diagrams render extra `<rect>`+`<text>` for a classifier that
+is NOT placed on the diagram via `t_diagramobjects` (or XMI
+`<elements>` block), but IS referenced as a generalization parent
+by a connector on the diagram.
+
+Reference SVG for `EAID_5A43833E_680B_4a90_8931_0C902304E029` has:
+
+```
+<rect x="161" y="161" width="179" height="80" .../>
+<text>_AbstractGeometricAggregate</text>
+```
+
+The classifier `_AbstractGeometricAggregate` is the general parent
+of one of the placed children, but is NOT placed itself. EA renders
+a phantom box at the parent end of the generalization connector.
+
+## Discriminator (hypothesis)
+
+When a connector's `EOID` references a `DUID` that is NOT in the
+placed-elements index, EA renders a minimal phantom box at the
+connector's endpoint coordinate. The phantom box shows the parent
+classifier's name and stereotype but no attributes/operations.
+
+## Acceptance
+
+- Detect connectors whose endpoint DUID has no matching placed
+  element.
+- Render a phantom box at the connector's endpoint with the
+  referenced classifier's header.
+- Bench rect delta improves by N where N is the count of phantom
+  parents across the plateau reference set.
+
+## Related
+
+- TODO-D 26 (phantom class headers from connector endpoints) —
+  same root cause, separate TODO for tracking.