ea 0.4.0 → 0.5.0

data/TODO.diagrams/53-remaining-example-gaps.md

@@ -0,0 +1,86 @@
+# TODO-D 53: Remaining example parity gaps (deferred)
+
+## Summary
+
+This round achieved 15/27 → 17/27 example diagrams at 100% parity
+(plus 2/2 simple + 1/2 test, 20/22 basic, 5/6 ArcGIS).
+
+```
+simple              2/2   matched    100% ✓
+ArcGISWorkspace     5/6   matched
+basic              20/22  matched
+test                1/2   matched
+```
+
+## Remaining basic.qea gaps (7 diagrams, all minor)
+
+| Diagram | rect | path | polygon | text | Root cause |
+|---------|------|------|---------|------|------------|
+| Package Imports | -6 | -18 | 0 | -4 | visibility icons missing |
+| Object with Value Specifications | 0 | -6 | 0 | -19 | object instance format |
+| Objects as Instances of Classes | 0 | -4 | 0 | -9 | object instance format |
+| Domain Model | +3 | -7 | +1 | -8 | tree-routed bezier paths |
+| Basic Object Diagram | 0 | -3 | 0 | -2 | (object value slots) |
+| Basic Class with Receptions | 0 | +5 | -2 | -3 | extra compartment dividers |
+| Composition with Substitution | 0 | 0 | 0 | -1 | nested class display_name |
+
+## test.qea gap
+
+`Test Model` diagram: r=-15, p=-58, po=0, t=-11. Needs visibility
+icons + Package element attribute rendering.
+
+## Implementation paths (in priority order)
+
+### TODO-D 54: Visibility icons (TODO-D 51 expansion)
+
+EA renders 5-6 element decorations per attribute row when
+`ShowIcons=1`:
+- 1 outer rect (11x14, pale yellow + blue stroke)
+- 1 inner rect (11x4, white)
+- 1 horizontal divider path (midline)
+- 3-4 short "text line" paths inside
+
+This closes `Test Model` (r=-15, p=-58) and `Package Imports`
+(r=-6, p=-18). 73+ missing elements across examples.
+
+Implementation: `Compartment::VisibilityIcon` + discriminator in
+`RenderContext` (default hidden, opt-in via DiagramElement#icon_visible
+or DisplayConfig#show_icons).
+
+### TODO-D 55: Object instance format
+
+EA renders object instances as:
+- Header: `Object 01 / roleOne: Class A` (instance name + role + classifier)
+- Slot rows: `attribute = value` for each slot
+- Package qualifier: `(from Objects)`
+
+Current code renders them as plain classes with the qualified class
+name. Requires new `Ea::Model::InstanceSpecification` model + QEA
+parser support + ObjectInstanceRenderer compartment.
+
+### TODO-D 56: Tree-routed bezier paths
+
+EA renders tree-routed connectors with cubic bezier curves
+(C commands) for smooth paths. We render straight L segments.
+The visual is similar but path count differs. Detection: when a
+connector has 3+ waypoints with `tree:` style, emit bezier.
+
+## Architectural decisions documented this round
+
+1. **«property» label OY-gap rule**: real geometry check (15px
+   threshold) instead of always-true.
+2. **Implicit connector visibility**: render Nesting when
+   `tree:` style is set, filter otherwise.
+3. **Plus marker**: new `Marker::Plus` kind for Nesting connector
+   "+" decoration (lazy registration architecture).
+4. **Marker registration**: per-file `Registry.register(...)` +
+   `Marker.ensure_builtins_registered!` — OCP-friendly, no
+   autoload cycle.
+
+## Final state
+
+- 1764 specs pass
+- Zero code-quality violations
+- basic.qea: 8 → 9 perfect diagrams (out of 22)
+- test.qea: 0 → 1 perfect diagram (out of 2)
+- simple.qea: 2/2 perfect

data/TODO.diagrams/54-display-name-nested-classes.md

@@ -0,0 +1,40 @@
+# TODO-D 54: display_name for nested classes (DONE)
+
+## Before
+
+`HeaderLines#display_name` used both `visually_nested` AND
+`nested_class_qualifier?` to decide whether to render the
+qualified name:
+
+```ruby
+return name if visually_nested &&
+               classifier.is_a?(Ea::Model::Classifier) &&
+               nested_class_qualifier?(classifier, name)
+```
+
+The `visually_nested` check is a position-based heuristic (child
+bounds inside parent bounds). For basic.qea's "Composition with
+Substitution" diagram, Class B.1, B.2, B.3 are placed at y=-330
+(off-canvas) while Class B is at y=-172. The position check returns
+false, but the reference renders "Class B::Class B.1" (qualified).
+
+## After
+
+The `visually_nested` check is dropped. The `nested_class_qualifier?`
+check alone determines the display:
+
+```ruby
+return name if classifier.is_a?(Ea::Model::Classifier) &&
+               nested_class_qualifier?(classifier, name)
+```
+
+The qualifier is a parent class name (not a package name) when it
+differs from the classifier's package name. EA always shows the
+parent-class qualifier regardless of visual position.
+
+## Verification
+
+- basic.qea "Composition with Substitution": text delta -1 → 0 ✓
+- 1764 specs pass
+- Plateau unchanged (text overlap 64.5%)
+- simple.qea unchanged (100%)

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.