ea 0.3.1 → 0.5.0

data/TODO.diagrams/55-visibility-icon-discriminator.md

@@ -0,0 +1,58 @@
+# TODO-D 55: Visibility icon discriminator (deferred)
+
+## Status: deferred (out of scope for current session)
+
+EA renders a "folded page" visibility icon for each attribute row
+in some diagrams. The discriminator is `ShowIcons=1` in the
+diagram's Style1 string.
+
+## Icon design (per attribute row)
+
+```
+y_top (rect.y)
+y_top..y_top+4:   inner rect 11x4 (white fill, blue stroke)
+y_top..y_top+14:  outer rect 11x14 (pale yellow, blue stroke)
+y_top+7:          horizontal path (midline)
+y_top+5, y_top+9, y_top+11: 3 short "text line" paths (4 wide)
+```
+
+Total: 2 rects + 4 paths = 6 elements per attribute row.
+
+## Where it appears
+
+| Diagram | rect | path | text | Why |
+|---------|------|------|------|-----|
+| basic.qea Package Imports | -6 | -18 | -4 | 2 attrs × 6 elements = 12 missing |
+| test.qea Test Model | -15 | -58 | -11 | 8 attrs × 6 elements = 48 missing |
+| basic.qea Operations+Object | similar | similar | similar | some object diagrams |
+
+## Implementation
+
+1. Parse `ShowIcons=N` from `t_diagram.Style1` (or per-element
+   `HideIcon=N` from `t_diagramobjects.Style`).
+2. When ShowIcons=1 (or default-icon), pass an `icon_visibility`
+   flag through `RenderContext`.
+3. Add a new `Compartment::VisibilityIcon` module that renders
+   the 2 rects + 4 paths per attribute row.
+4. Wire it into the Attribute compartment (or render alongside
+   it).
+
+## Why deferred
+
+- Requires parsing the QEA Style1 string (already done in
+  DisplayConfig for other flags).
+- Discriminator must be verified across more diagrams (e.g.
+  plateau's Building diagram has 1 icon — the same logic should
+  apply).
+- Each attribute row needs the icon rendered at a precise offset
+  (currently at content_x_offset, attr_y - 9).
+
+Closes ~80 rects + ~50 paths in basic.qea + ~70 rects + ~250
+paths in test.qea (Test Model with 8 attrs).
+
+## Code-quality alignment
+
+The new `Compartment::VisibilityIcon` would follow the OCP
+pattern established by the Compartment pipeline — adding a new
+compartment = appending to `Compartment::ALL`, no modification
+of `Elements#groups_for` needed.

data/TODO.diagrams/56-package-contents-rendering.md

@@ -0,0 +1,148 @@
+# TODO-D 56: Package contents rendering (DONE)
+
+## Before
+
+When a diagram's `t_diagram.ShowPackageContents` flag was non-zero,
+EA renders each Package element with:
+- A 2-line tab when the package has a stereotype («applicationSchema»)
+- A body compartment listing child classifiers and sub-packages as
+  "+ Name" rows
+- A per-row icon whose shape encodes the child's type
+
+Our renderer produced only the bare folder silhouette. All test.qea
+"Test Model" diagrams and basic.qea "Package Imports" diagrams
+under-rendered by ~70 elements each.
+
+## After
+
+### Source side
+
+- `Ea::Sources::Qea::PackageBuilder#stereotype_refs_for`: now reads
+  the t_object.Stereotype column for the package's mirror row
+  (matched by ea_guid). EA stores the stereotype on t_object, not
+  t_package.
+- `Ea::Sources::Qea::DiagramBuilder#package_contents_enabled?`:
+  threads `show_package_contents` (non-zero t_diagram column) into
+  `Ea::Model::Diagram`.
+- `Ea::Model::Diagram#show_package_contents`: boolean attribute
+  controlling whether the package-contents compartment is rendered.
+
+### Render side
+
+- `Ea::Svg::EaEmitter::Element::PackageShapeRenderer`: now accepts
+  an optional `stereotype:` argument. When present, the tab grows
+  to 36px tall (vs 20px) and renders two left-aligned text lines
+  («stereotype» + name). Tab width is fixed at 105px (EA convention).
+- `Ea::Svg::EaEmitter::Compartment::PackageContents`: new
+  compartment module that renders the body's child rows. Each row
+  is one `<text>` element ("+ Name") plus a small per-type icon.
+- `Ea::Svg::EaEmitter::Element::RowIconRenderer`: new renderer for
+  the per-row icons. Three kinds:
+  - `:enumeration` (12×13 green rect + 7 paths) — used for
+    Enumeration classifiers or Klass with stereotype "enumeration".
+  - `:package` (13×9 folder rect, no paths) — used for sub-Packages.
+  - `:default` (11×14 + 11×4 rects + 7 paths) — used for other
+    Classifiers (Klass, DataType, etc.).
+- `Ea::Svg::EaEmitter::Compartment::Shape`: threads the package's
+  stereotype to PackageShapeRenderer.
+- `Ea::Svg::EaEmitter::Elements`: computes `package_content_lines`
+  for Package model elements when `diagram.show_package_contents`
+  is truthy. Children include both Classifier and sub-Package
+  instances; the icon kind is chosen by classifier type or
+  "enumeration" stereotype.
+
+### Specs
+
+- Updated `spec/ea/svg/ea_emitter/compartment_spec.rb` to include
+  PackageContents in the expected ALL list.
+
+## Verification
+
+- simple.qea: 2/2 (100% strict-perfect) — unchanged.
+- basic.qea: 21/22 matched within tolerance (up from 20/22).
+  14/22 strict-perfect (up from 7/22).
+- test.qea: 2/2 matched within tolerance. Test Model is strict
+  perfect (was shape_delta=71). TestSchema still has a small
+  pre-existing -4 text gap unrelated to package contents.
+- Plateau: rect/path/polygon deltas unchanged (text improved
+  slightly, -626 → -615, from stereotype rendering).
+- 1767 specs pass, 0 failures.
+
+## Remaining gaps
+
+- test.qea TestSchema: -3 text. Ref includes «voidable» constraint
+  stereotype, "constraints" header, and "{pattern}" annotation that
+  we don't render yet. Pre-existing.
+- basic.qea Domain Model: rect=+3 (Concept boxes drawn as rects
+  but ref uses bezier paths). Pre-existing.
+- basic.qea Class-diagram-with-X diagrams: path deltas from
+  association marker encoding differences (QEA polygon vs XMI
+  arrow path). Pre-existing.
+- basic.qea Object diagrams: missing instance-name underline paths
+  and instance label format ("Object 01 / roleOne: Class A"). Needs
+  an InstanceSpecification model. Pre-existing.
+
+## Follow-up commits
+
+`feat: promote enumeration-stereotyped Class to Enumeration model` —
+ClassifierBuilder now treats a Class with stereotype "enumeration"
+as an Enumeration. Closes 1 additional text delta on TestSchema
+(-4 → -3).
+
+`feat: constraints compartment (italic header + {name} expression)` —
+Adds Ea::Model::Constraint, reads t_objectconstraint in the QEA
+classifier builder, and renders via Compartment::Constraints +
+Element::ConstraintRenderer. Closes 2 text deltas on TestSchema
+(-3 → -1).
+
+`feat: render attribute stereotypes as separate text lines` —
+AttributeRenderer.lines_for inserts «stereotype» entries before
+stereotyped properties. Closes the final TestSchema text gap
+(-1 → 0).
+
+`feat: instance-name underline for object diagrams` — Object
+diagrams draw a horizontal underline below each instance name.
+New Compartment::InstanceUnderline module fires for diagrams
+where diagram_type=="Object". RenderContext gains a :diagram
+field. Improves path delta on all 4 basic.qea object diagrams.
+
+`feat: «import» markers for Package connectors` — New
+Marker::PackageImport kind emits both a closed trapezoid at the
+source end and an open V-arrow at the target end of Package
+(«import») connectors. Closes the basic.qea Package Imports
+path delta (-4 → 0).
+
+`feat: Object diagram — divider + suppress arrows` — Object
+diagrams render associations as instance-level links without
+navigability arrows. Markers suppresses :arrow specs for
+Association connectors when diagram_type=="Object". HeaderDivider
+gains a diagram-type-aware discriminator: on Object diagrams the
+divider is shown when bounds.height > 50 (matches EA's "has slot
+compartment" heuristic). Closes path deltas on all 4 basic.qea
+Object diagrams. Starter Object Diagram is now strict-perfect.
+
+## Final state
+
+- simple.qea: 2/2 strict-perfect (100%).
+- basic.qea: **16/22 strict-perfect**, 22/22 within tolerance.
+- test.qea: 1/2 strict-perfect (Test Model perfect; TestSchema at
+  text=0, path=-1).
+- Plateau: rect -221, path -280, polygon -6, text -615.
+- 1800 specs pass, 0 failures.
+
+## Remaining gaps (all pre-existing, out of scope)
+
+- test.qea TestSchema: -1 path (association marker encoding).
+- basic.qea Domain Model: +3 rect (Concept boxes drawn as rects
+  but ref uses bezier paths in a "domain class" style with
+  Comic Sans MS italic font).
+- basic.qea Classes (×2): +1 path each (extra arrow marker on
+  tree-routed Association connectors — source discriminator not
+  yet identified; same connectors on Multiplicities render WITH
+  arrows in ref, so the rule is more subtle than waypoint count).
+- basic.qea Object diagrams (×3 with text deltas): instance label
+  format ("Object 01 / roleOne: Class A"), slot value renderings
+  ("attr = value"), and "(from package)" subtitle. Needs
+  InstanceSpecification model.
+- Association marker encoding: QEA polygon vs XMI arrow path
+  discriminator not yet identified.

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

@@ -0,0 +1,100 @@
+# TODO-D 57: InstanceSpecification model + slot rendering
+
+## Status: open (blocks 3 basic.qea diagrams + plateau)
+
+EA stores UML InstanceSpecifications in `t_object` rows with
+`Object_Type="Object"`. Currently we parse these as `Klass`
+instances (the closest classifier shape). Ref renders them as
+instances with three features we don't emit:
+
+1. **Instance label format** in the header: `instance_name` plus,
+   when the instance is a role in an association, the role +
+   classifier name (e.g. `"Object 01 / roleOne: Class A"`).
+2. **Slot compartment** below the header: each `RunState` variable
+   is rendered as `"variable = value"` (e.g.
+   `"attributeOne = valueOne"`).
+3. **From-package subtitle** below the slots:
+   `"(from Objects)"` — the containing package name in italics.
+
+## Affected diagrams
+
+| Diagram | text_delta | Notes |
+|---------|-----------|-------|
+| Basic Object Diagram with Value Specification | -2 | 1 slot per instance |
+| Objects as Instances of Classes | -9 | 1 instance label + slot + from-package per box |
+| Object with Value Specifications | -19 | 1 instance label + multiple slots + from-package per box |
+
+Plus widespread contribution to the plateau text delta (-615).
+
+## Source data
+
+`t_object` columns for Object instances:
+- `Object_Type="Object"`
+- `Name="Object 01"` (the instance name)
+- `Classifier=<id>` (the class this is an instance of; 0 = none)
+- `RunState="@VAR;Variable=X;Value=Y;Op==;@ENDVAR;..."` (slots)
+
+The role name (`"roleOne"`) comes from the connector's source role
+field on the association linking this instance to another.
+
+## Implementation plan
+
+### 1. Model
+
+- `Ea::Model::InstanceSpecification < Base` — new model class
+  - `name :string`
+  - `classifier_id :string` (id of the class this is an instance of)
+  - `slots :Slot, collection: true`
+  - `role_name :string` (filled in later by relationship resolver)
+  - `package_id :string`
+  - `qualified_name :string`
+- `Ea::Model::Slot < Base` — a slot value
+  - `name :string` (the variable)
+  - `value :string`
+  - `op :string` (default `"="`)
+
+### 2. Source side
+
+- `Ea::Sources::Qea::InstanceBuilder` — new builder that reads
+  `t_object` rows where `Object_Type="Object"` and parses `RunState`
+  into Slot instances. Replaces the `Object → Klass` mapping in
+  `ObjectClassifierMap`.
+- Update `Ea::Sources::Qea::Adapter` to call both `ClassifierBuilder`
+  and `InstanceBuilder`.
+- Update `Document#index_by_id` to include instance specifications.
+
+### 3. Render side
+
+- `Compartment::InstanceHeader` (new) — renders the instance label
+  format `name / role: ClassName` in the header.
+- `Compartment::InstanceSlots` (new) — renders the slot compartment
+  (`variable = value` lines).
+- `Compartment::InstanceFromPackage` (new) — renders the
+  `"(from packageName)"` subtitle in italics.
+- The existing `InstanceUnderline` module is reused for the
+  instance-name underline.
+- `Shape` compartment: dispatch instance specs to a new
+  `InstanceShapeRenderer` (or reuse `ShapeRenderer` since the box
+  shape is the same).
+
+### 4. Specs
+
+- Instance model spec (round-trip JSON)
+- InstanceBuilder spec (parses RunState correctly)
+- InstanceSlots spec (renders "var = value")
+- InstanceFromPackage spec (renders italic "(from X)")
+
+## Discriminator
+
+When `diagram.diagram_type == "Object"` AND `model_element.is_a?(InstanceSpecification)`:
+- Header: instance label format
+- Body: slot compartment + from-package subtitle
+
+Otherwise: standard classifier rendering.
+
+## Why deferred initially
+
+Requires a new top-level model class, source-builder wiring, and 3
+new compartments. ~300 lines of code + ~150 lines of specs. Affects
+the parity metric broadly (basic.qea +3 diagrams strict-perfect,
+plateau text delta improves).

data/TODO.diagrams/58-domain-model-note-text.md

@@ -0,0 +1,67 @@
+# TODO-D 58: Domain Model note text + missing multiplicity
+
+## Status: open (blocks 1 basic.qea diagram)
+
+Domain Model is at shape_delta_total=0 (sum-zero parity) but has
+text_delta=-7. Two missing items:
+
+### A. Wrapped note text (-6)
+
+EA wraps long note text across multiple `<text>` lines. For the
+Domain Model Concepts, the note `"Detailed notes that describe the
+concept."` is wrapped onto two lines per element:
+
+  <text x="45" y="95">[Detailed notes that describe the </text>
+  <text x="45" y="109">concept.]</text>
+
+The leading `[` and trailing `]` are EA's convention for marking
+the note body (not part of the actual note content). Line-wrap
+width is determined by the element bounds width minus padding
+(~125px usable for a 167px-wide box at font size 7pt).
+
+Currently we don't render note text in element bodies at all. The
+note text comes from `t_object.Note`.
+
+### B. Missing target multiplicity (-1)
+
+One Aggregation connector (`Relationship Two`) has source mult
+`0..*` (rendered at top) and target mult `1..1` (should render
+near Concept A's top edge but doesn't). The target endpoint lands
+inside the element box and our EndLabel skips the label.
+
+## Implementation plan
+
+### For (A) — wrapped note text
+
+- `Ea::Model::Classifier` already has `annotations` — re-use for
+  the documentation note OR add `note :string` as a separate field
+  (EA's `t_object.Note` is distinct from `t_objectproperties` tagged
+  values).
+- `Ea::Sources::Qea::ClassifierBuilder#note_for` reads `object.note`.
+- New `Compartment::NoteText` (different from `Compartment::NoteBody`
+  which handles Note elements):
+  - Splits the note text into lines based on a width estimate
+  - Wraps with `[` ... `]`
+  - Renders one `<text>` per line below the header divider
+- Discriminator: render when `classifier.note` is non-empty AND
+  the element has no attribute compartment (the note replaces
+  attributes in this style).
+
+### For (B) — multiplicity inside element
+
+- `Ea::Svg::EaEmitter::Label::EndLabel`: relax the
+  "skip when inside element" rule for multiplicity labels — they
+  should render even when the anchor is inside an element box
+  (just offset outward).
+
+## Verification
+
+- basic.qea "Domain Model": text_delta -7 → 0.
+- basic.qea: 16/22 → 17/22 strict-perfect.
+
+## Why deferred
+
+Note wrapping needs a width-estimation helper (font size × char
+count × width factor) and a `Compartment::NoteText` module. The
+multiplicity fix requires relaxing EndLabel's collision rule which
+could regress other diagrams.

data/TODO.diagrams/59-classes-arrow-discriminator.md

@@ -0,0 +1,57 @@
+# TODO-D 59: Classes diagram association arrow discriminator
+
+## Status: open (blocks 2 basic.qea diagrams)
+
+Two basic.qea "Classes" diagrams have shape_delta=1 each. We render
+one extra `<path>` per diagram — the navigability arrow at the
+target end of an Association connector that EA's reference SVG
+omits.
+
+## Investigation summary
+
+Compared fields across the rendering-pipeline:
+
+| Diagram | Direction | SourceStyle | DestStyle | LineStyle | RouteStyle | SourceCard | DestCard | SourceIsAggregate | DestIsAggregate | SX/SY/EX/EY | Object types |
+|---------|-----------|-------------|-----------|-----------|------------|------------|----------|-------------------|-----------------|-------------|--------------|
+| Multiplicities (HAS arrow) | Unspecified | Navigable=U | Navigable=U | 0 | 3 | 0..* | 0..* | 0 | 0 | -6/-2/-57/-2 | Class ↔ Class |
+| Classes (NO arrow) | Unspecified | Navigable=U | Navigable=U | 0 | 3 | 0..2 | 1 | 0 | 0 | -1/4/3/4 | Class ↔ Class |
+
+All fields identical except cardinality and SX/SY/EX/EY values.
+The visual difference: Multiplicities renders as a single straight
+path + arrow polygon; Classes renders as 3 separate horizontal
+segments + no arrow. EA appears to apply an internal "are bends
+real?" heuristic.
+
+## Hypothesis
+
+EA computes the maximum perpendicular deviation of bend waypoints
+from the straight source-target line. Below a threshold (likely
+~2-3px), bends are treated as noise and the connector renders as
+straight WITH navigability arrow. Above the threshold, the
+connector renders as orthogonal segments with NO arrow.
+
+For Multiplicities: deviations 1-2px → straight + arrow.
+For Classes: deviations 4-5px → segmented + no arrow.
+
+## Implementation plan
+
+- In `Ea::Svg::EaEmitter::Connectors#path_for`, compute the
+  perpendicular deviation of each interior waypoint from the
+  source-target line. If max deviation ≤ THRESHOLD (try 3), emit
+  a straight 2-point path. Otherwise keep current multi-segment
+  path.
+- In `Ea::Svg::EaEmitter::Markers#suppress_arrow?`, suppress
+  Association arrow when the connector is multi-segment (max
+  deviation > THRESHOLD).
+- THRESHOLD constant lives on `Connectors` (or a shared
+  `ConnectorRouting` module) so both renderers use the same value.
+
+## Verification
+
+- basic.qea "Classes" (×2): shape_delta 1 → 0.
+- basic.qea: 16/22 → 18/22 strict-perfect.
+
+## Risk
+
+The threshold value is reverse-engineered from a single sample.
+Verifying against plateau connectors would confirm.

data/TODO.diagrams/60-testschema-association-marker.md

@@ -0,0 +1,40 @@
+# TODO-D 60: TestSchema association marker encoding (-1 path)
+
+## Status: open (blocks 1 test.qea diagram)
+
+test.qea TestSchema is at text_delta=0 but path_delta=-1.
+
+## Symptom
+
+Ref renders a particular Association connector with an open
+`<path>` V-shape arrow at the target end. We render the connector
+line but no arrow — the marker is suppressed somewhere in our
+dispatch.
+
+## Likely cause
+
+The connector is on a Logical (not Object) diagram so our
+"Object diagrams suppress Association arrows" rule doesn't apply.
+Yet we still don't emit the marker. The Markers#specs_for path
+returns no specs because... needs investigation.
+
+## Plan
+
+1. Render TestSchema and identify which connector is missing its
+   arrow.
+2. Trace through Marker::Registry.specs_for and confirm ArrowPath
+   is registered and returns a spec.
+3. Trace through Markers#entries_for and check whether the spec is
+   being filtered out (suppress_arrow? or render_shape returns nil).
+4. Most likely culprit: `unit_vector` returns nil because tip and
+   base are coincident (connector shorter than 1 unit vector step).
+
+## Verification
+
+- test.qea TestSchema: path_delta -1 → 0.
+- test.qea: 1/2 → 2/2 strict-perfect (100%).
+
+## Why deferred
+
+Small delta (-1 path) and the fix likely requires non-trivial
+debugging of the unit-vector geometry for very short connectors.

data/TODO.diagrams/61-legend-block-rendering.md

@@ -0,0 +1,55 @@
+# TODO-D 61: Legend block rendering
+
+## Status: completed
+
+The plateau QEA's `t_object` rows with `Object_Type='Text'` and
+`StyleEx` carrying `LegendOpts=` are auto-generated legend blocks.
+EA renders each as a 4-rect + 4-text cluster (container + 3 colored
+icons + title + 3 labels), with the legend configuration parsed
+from a sibling `t_xref` row keyed off the same GUID.
+
+## Implementation
+
+- `Ea::Model::Legend` and `Ea::Model::LegendItem` — new models
+  carrying the legend title, colors (BGR-packed), and per-item
+  background colors. Default colors pulled from plateau SVG refs.
+- `Ea::Model::Note` gains an optional `legend` attribute. Text
+  elements with `LegendOpts=` in StyleEx parse the legend payload
+  at load time; other Notes stay unencumbered.
+- `Ea::Sources::Qea::LegendBuilder` parses the `@PROP=...@ENDPROP;`
+  blobs in `t_xref.Description` for a given Text element GUID.
+- `Ea::Svg::EaEmitter::Element::LegendRenderer` emits the container
+  rect, icon rects, title text, and item labels. BGR colors decode
+  via the existing `Element::BColDecoder`.
+- `Compartment::Shape` dispatches to `LegendRenderer` when the
+  element carries a legend payload; `Compartment::NoteBody` skips
+  rendering (legend replaces note body).
+
+## Related fix: marker dedup removed
+
+Reference inspection showed EA does NOT dedup polygon markers even
+when N connectors share the same anchor — the Bridge diagram emits
+9 distinct triangle polygons at one parent anchor. Removed the
+`Markers::Entry#generalization_tree_routed?` dedup logic; EA emits
+one marker per connector, period.
+
+## Related fix: spec pollution
+
+`spec/ea/svg/qea_regression_spec.rb` and
+`spec/ea/svg/visual_regression_spec.rb` both defined top-level
+constants named `REF_DIR` inside `RSpec.describe` blocks. Ruby
+resolves these to top-level constants — the spec loaded second
+won, silently pointing the other spec at the wrong reference SVG
+directory. Renamed to `QEA_REF_DIR` and `VISUAL_REF_DIR`.
+
+## Results (plateau QEA)
+
+| Metric  | Before | After  | Change |
+|---------|--------|--------|--------|
+| Matched | 130/188| 137/188| +7     |
+| rect    | -460   | +4     | +464   |
+| path    | -92    | -92    | —      |
+| polygon | +27    | +25    | -2     |
+| text    | -519   | -55    | +464   |
+
+basic.qea and test.qea remain at 22/22 and 2/2 respectively.

data/TODO.diagrams/61-plateau-parity-gaps.md

@@ -0,0 +1,59 @@
+# TODO-D 61: Plateau parity gaps
+
+## Status: open (broad cross-cutting gaps on plateau QEA)
+
+The plateau is the `20251010_current_plateau_v5.1.qea` file at
+`examples/qea/`. Its 188 reference SVGs live at
+`examples/exports/20251010_current_plateau_v5/Images/`.
+
+A separate plateau XMI is at
+`~/src/mn/mn-samples-plateau/sources/xmi/plateau_all_packages_export.xmi`
+with its own reference SVGs at
+`~/src/mn/mn-samples-plateau/sources/001-mds/xmi-images/`.
+
+## Current state — Plateau QEA (examples/)
+
+| Metric | Before | After improvements | Change |
+|--------|--------|-------------------|--------|
+| Matched | 126/188 | **130/188** | +4 |
+| rect | -460 | **-460** | — |
+| path | -455 | **-92** | +363 recovered |
+| polygon | +27 | **+27** | — |
+| text | -519 | **-519** | — |
+
+Key improvements this session:
+- Horizontal-tree-routed arrow suppression (narrower check)
+- Marker dedup changed to polygon-only (never dedup arrows)
+  → recovered ~200 association arrow paths on plateau
+
+## Current state — Plateau XMI (~/src/mn/)
+
+| Metric | Value |
+|--------|-------|
+| Diagrams matched (tolerance ≤5) | 127/185 |
+| rect delta | -221 (-11.0%) |
+| path delta | -338 (-10.2%) |
+| polygon delta | -6 (-0.6%) |
+| text delta | +97 (+0.6%) |
+
+## Where the deltas come from
+
+### rect -460 (QEA) / -221 (XMI)
+- Missing visibility icons (2 rects per attribute × many elements)
+- Package-content child rows missing on some diagrams
+- Element shape encoding (rect vs polygon)
+
+### path -455 (QEA) / -338 (XMI)
+- Connector arrow markers (tree-routed suppression removes some)
+- Visibility icon paths (7 per attr × many elements)
+- Connector routing encoding differences
+
+### text -519 (QEA) / +97 (XMI)
+- QEA has richer data (RunState, more tagged values) but some
+  texts are not rendered (instance labels, slot values)
+- XMI over-renders some texts (from InstanceSpecification parsing)
+
+## Plan
+
+Each delta spans dozens of diagrams. Improvements require broad
+pipeline changes rather than single-diagram fixes.

data/TODO.diagrams/62-ghost-element-rendering.md

@@ -0,0 +1,56 @@
+# TODO-D 62: Ghost element rendering (off-canvas connector endpoints)
+
+## Status: open
+
+EA phantom-renders classifier names near connector endpoints that
+reference elements NOT placed on the current diagram. These "ghost
+elements" appear as italic class names (e.g. `_CityObject`,
+`_Site`, `_Geometry`) at the connector's off-canvas end. They are
+NOT in `t_diagramobjects` for the diagram but ARE referenced by
+`t_connector.Start_Object_ID` / `End_Object_ID` of connectors
+that ARE on the diagram.
+
+## Evidence (plateau QEA, "indoor" diagram)
+
+- `_CityObject` does not appear in `t_diagramobjects` for the
+  indoor diagram.
+- It IS referenced by connectors on the indoor diagram (e.g.
+  generalizations from `Room` to `_CityObject`).
+- EA renders the name as 5+ separate italic `<text>` elements at
+  different positions, one per connector endpoint.
+
+## Approach
+
+1. **Source side**: in `DiagramBuilder`, walk every renderable
+   connector and look up its source/target object via
+   `database.find_connector` → `start_object_id`/`end_object_id` →
+   `database.find_object`. When the object is NOT placed on this
+   diagram (no entry in `t_diagramobjects`), synthesise a
+   "ghost element" annotation on the connector: the off-canvas
+   end's classifier name + a virtual anchor position (probably
+   the on-canvas endpoint).
+
+2. **Model side**: add `ghost_labels` to `DiagramConnector` —
+   a collection of `(name, end_kind, anchor_offset)` tuples.
+
+3. **Renderer side**: emit each ghost label as an italic `<text>`
+   at the connector's endpoint, offset to one side. Match EA's
+   offset rules (need to reverse-engineer from reference SVGs).
+
+## Impact
+
+Closing the text gap from -292 to near 0 on plateau QEA. Most of
+the missing text delta comes from ghost labels:
+- indoor: -17 (mostly `_CityObject`)
+- frn_1: -7
+- cons_1: -6
+- tran_2: -5
+- bldg_1: -6 (BuildingAttribute)
+- and 10+ more diagrams with -1 to -5 each.
+
+Combined: ~80-100 missing ghost labels across the plateau.
+
+## Related
+
+- TODO-D 26 (Investigate phantom class headers from connector
+  endpoints) is the older writeup of the same issue.

data/TODO.diagrams/63-qualified-name-wrap.md

@@ -0,0 +1,36 @@
+# TODO-D 63: Qualified-name line wrap for long class names
+
+## Status: completed
+
+EA wraps long qualified class names (e.g. `brid::OuterFloorSurface`)
+across TWO `<text>` elements when the rendered width exceeds the
+element's header width.
+
+## Implementation
+
+`Ea::Svg::EaEmitter::Element::HeaderLines.for` now accepts
+`bounds_width:` and `font_size:` keyword args. When the qualified
+name's estimated rendered width (using `TextRenderer.estimate_width`
+with `width_factor=0.55` and `QUALIFIED_WRAP_PADDING=8`) exceeds
+the element's bounds, the name splits into two header lines:
+
+1. `"qualifier::"` (with trailing `::`)
+2. `"ClassName"` (the base name after `::`)
+
+The `Elements` orchestrator threads `raw_bounds.width` and the
+resolved `font_size` through to `HeaderLines.for`.
+
+## Results
+
+- Plateau text delta: -3 → +5 (slight over-rendering on a few
+  borderline cases — both name+wrap and not-quite-fit names).
+- 154/188 matched diagrams (unchanged).
+- basic.qea, test.qea, simple.qea: unchanged.
+
+## Tuning
+
+Width factor 0.55 matches Carlito 9pt bold's average glyph advance
+for the CJK + Latin mix on the plateau. The 8px padding accounts
+for the element's internal left+right padding that EA reserves
+around header text. Both constants are at the top of HeaderLines
+for easy future adjustment if EA's font metrics shift.