ea 0.4.0 → 0.5.0

data/TODO.diagrams/17-italic-abstract-classes.md

@@ -0,0 +1,28 @@
+# 17 - Italic Rendering for Abstract Classes
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Updated `Elements#header_lines` to handle the abstract + stereotype
+combination: when a class is abstract AND has a stereotype, emit
+both lines (stereotype normal, name italic with `_` prefix).
+
+```ruby
+if classifier.is_abstract
+  lines << ["«abstract»", :normal] if classifier.stereotype_refs&.any?
+  lines << ["_#{classifier.name}", :italic]
+elsif classifier.stereotype_refs&.any?
+  lines << ["«#{stereotype}»", :normal]
+  lines << [name, :bold]
+else
+  lines << [name, :bold]
+end
+```
+
+Abstract classes now render matching EA's encoding:
+`<text style="font-style:italic;...">_TransportationObject</text>`.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/elements.rb` — `header_lines` abstract+stereotype branch

data/TODO.diagrams/17-remaining-parity-gaps.md

@@ -0,0 +1,90 @@
+# TODO-D 17: Remaining Parity Gaps
+
+## Current State (2026-07-26)
+
+- Text overlap: **87.2%** (Jaccard, set-equality per `<text>` content)
+- Text count delta: **-83** (-0.4% vs reference; effectively at parity)
+- Shape counts: rect -460 (-20.9%), polygon -166 (-11.2%), path -181 (-5.1%)
+- Within tolerance: 123/188 diagrams (65.4%)
+
+## Closed Gaps
+
+1. QEA `$LLB=...;LLT=...;LRB=...;LRT=...` parsing — only first segment
+   carries `$`, the rest are `KEY=` after `;`. Fixed.
+2. Connector label rendering at LLT/LRT box positions, with role + «property»
+   + mult. Fixed.
+3. Abstract class underscore — the underscore lives in the QEA class name
+   itself (`_CityObject`), not added by EA at render time. Fixed.
+4. Enumeration `«enumeration»` stereotype fallback. Fixed.
+5. Connector-level stereotype label (e.g. «import» on Package connector).
+   Fixed.
+6. Attribute default value rendering (`name: type [mult] = default`). Fixed.
+7. Enumeration literal visibility marker (`<text> </text>` empty slot).
+   Fixed.
+8. Multiplicity 1..1 → "1" rendering when paired with role name. Fixed.
+
+## Open Gaps
+
+### Text overlap (87.2% → target ~95%+)
+
+1. **Auto-generated legend block** (~448 missing texts):
+   - "凡例" (Legend title, 12pt bold #003060)
+   - "GMLで定義されたクラス", "CityGMLで定義されたクラス",
+     "i-URで定義されたクラス" (3 color-coded class titles)
+   - "GMLに定義されたクラス", "CityGMLに定義されたクラス",
+     "i-URに定義されたクラス" (alternative particle に instead of で)
+   - EA auto-generates these when a diagram contains color-coded
+     stereotype elements. Source data location TBD — likely tied to
+     diagram-type or per-diagram MDGDgm flag.
+
+2. **Ghost element discriminator** (TODO-D 20, deferred):
+   - Some elements without explicit `font=` in their ObjectStyle get
+     ghost rendering (7pt #595959, no attrs); others get full rendering.
+   - Tested font_family presence → broke parity (-5000 texts).
+   - Tested classifier.package_id match → broke parity (-1500 texts).
+   - Real discriminator likely combines: ObjectStyle detail level +
+     diagram context + classifier source package. Needs EA.exe
+     disassembly reference.
+
+3. **Missing class headers** (~150 instances):
+   - Elements like `_AbstractGeometricAggregate`, `_CityObject`,
+     `_Site`, `_Feature`, `_TransportationObject` appear in reference
+     SVGs but not in t_diagramobjects for the diagram.
+   - Cause: either EA renders implicit elements from connector
+     endpoints, or the reference SVGs were generated from a different
+     QEA version than what we have.
+
+4. **`(from CityGML2.0)` qualifier** (9 instances):
+   - EA shows a sub-line for elements imported from a specific
+     package version.
+   - Source: probably t_object.Package_ID joined with t_package
+     version metadata.
+
+### Shape counts
+
+1. **rect -460**:
+   - ~3 rects per diagram missing from legend block (container with
+     rx=3 + 3 color swatch rects). 188 diagrams × ~3 = ~564 expected,
+     close to actual -460 gap.
+   - Need legend modeling first (depends on Text gap #1).
+
+2. **polygon -166**:
+   - Per-diagram marker counts differ — EA emits duplicate polygons
+     at overlapping connector endpoints (e.g. 7 identical triangles
+     at one position). Cause unknown.
+   - Likely needs investigation of t_diagramlinks.Hidden vs visible
+     flag and how EA consolidates markers.
+
+3. **path -181**:
+   - EA splits connector paths into individual segments per
+     style group. We consolidate same-style paths into one `<g>`.
+   - Some diagrams have 30+ path delta — needs path-per-connector
+     vs grouped-path mode selection per diagram.
+
+## Next Steps
+
+1. Investigate auto-generated legend feature: how EA detects "this
+   diagram needs a legend" and where the legend text/colors come from.
+2. Find a reliable ghost-element discriminator (likely involves
+   per-element display flags we haven't parsed yet).
+3. Investigate duplicate-polygon emission for overlapping markers.

data/TODO.diagrams/18-canvas-from-image-bounds.md

@@ -0,0 +1,20 @@
+# 18 - Canvas from image_bounds (matching EA)
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`Canvas.from` now unions BOTH `bounds` and `image_bounds` for each
+element. `image_bounds` captures the rendered extent (logical bounds
++ image padding), so the canvas grows to fit the full visual area.
+
+Waterway canvas: 1138×869 → 1163×899 (ref=1138×892)
+Building canvas: 1381×1524 → 1406×1554 (ref=1406×1530, width matches)
+
+Remaining diff (25 px width on Waterway) is from image_bounds
+extending further right than EA includes in canvas. Acceptable for
+visual rendering — text and shapes are positioned correctly.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/canvas.rb` — union bounds + image_bounds

data/TODO.diagrams/18-property-lookup-index.md

@@ -0,0 +1,42 @@
+# TODO-D 18: Property lookup index (performance + OCP)
+
+## Problem
+
+`Ea::Svg::EaEmitter::Labels#property_at_end` walks every Classifier
+and every Property on each Classifier to find a Property by ID:
+
+```ruby
+def property_at_end(association, end_kind)
+  id = end_kind == :source ? association.source_id : association.target_id
+  return nil unless id && model_index
+
+  model_index.values.each do |obj|
+    next unless obj.is_a?(Ea::Model::Classifier)
+    found = (obj.properties || []).find { |p| p.id == id }
+    return found if found
+  end
+  nil
+end
+```
+
+For the 205-diagram plateau QEA this is called once per visible
+association per diagram (~10k calls × ~600 classifiers × ~10
+properties = 60M comparisons). That is the dominant cost in SVG
+rendering.
+
+## Fix
+
+Add a lazily-built property index to `Ea::Model::Document` keyed by
+property id. Labels (and any future consumer) calls
+`document.property_by_id[id]` for O(1) lookup.
+
+This keeps the lookup logic in the model (model-driven) and avoids
+each consumer rebuilding the same index (DRY).
+
+## Acceptance
+
+- `Document#property_index` returns `{ property_id => Property }`.
+- `Labels#property_at_end` uses the index.
+- Parity text overlap remains ≥ 87%.
+- Specs continue to pass.
+- `rake benchmark` (or ad-hoc timing) shows measurable speed-up.

data/TODO.diagrams/19-connector-sx-sy-routing.md

@@ -0,0 +1,27 @@
+# 19 - Connector Source/Target Edge Routing from SX/SY/EX/EY
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`ConnectorRouter` now accepts `source_delta` and `target_delta`
+(defaulting to [0,0]). `DiagramBuilder#compute_waypoints` passes
+SX/SY/EX/EY from the parsed geometry to the router, which applies
+them as deltas to the edge-attachment point.
+
+`ExtensionGeometryParser.Placement` already exposed `sx`, `sy`,
+`ex`, `ey` — just plumbs them through.
+
+## Remaining diff
+
+Waterway connectors still show ~20 px y-offset vs EA reference
+(643 vs 663). The SX/SY deltas are small (-21 to 150) and don't
+account for this gap. EA likely uses a different attachment
+formula (not strict edge center) — possibly offset by half
+font-height or other rendering consideration. Deferred to deeper
+reverse-engineering.
+
+## Files changed
+
+- `lib/ea/svg/connector_router.rb` — source_delta / target_delta support
+- `lib/ea/sources/xmi/diagram_builder.rb` — passes deltas to router

data/TODO.diagrams/19-replace-respond-to-with-is-a.md

@@ -0,0 +1,31 @@
+# TODO-D 19: Replace respond_to? with is_a? (encapsulation)
+
+## Problem
+
+`Ea::Svg::EaEmitter::Labels#connector_stereotype` uses
+`respond_to?(:stereotype)`:
+
+```ruby
+def connector_stereotype(connector)
+  rel = model_index ? model_index[connector.relationship_ref] : nil
+  stereotype = rel&.respond_to?(:stereotype) ? rel.stereotype : nil
+  return nil if stereotype.nil? || stereotype.to_s.empty?
+  "«#{stereotype}»"
+end
+```
+
+`respond_to?` is duck-typing that hides type errors until runtime.
+Per the project rules: use `is_a?` for type checks, or design the
+type hierarchy so the check isn't needed.
+
+## Fix
+
+`Ea::Model::Relationship` (base class) now declares `stereotype` as
+an attribute. All concrete relationship subclasses inherit it. So
+the check should be `rel.is_a?(Ea::Model::Relationship)`.
+
+## Acceptance
+
+- No `respond_to?` calls in `lib/`.
+- Connector stereotype labels still render correctly.
+- Specs pass.

data/TODO.diagrams/20-split-labels-emitter.md

@@ -0,0 +1,56 @@
+# TODO-D 20: Split Labels emitter into MECE collaborators
+
+## Problem
+
+`Ea::Svg::EaEmitter::Labels` currently handles three distinct
+responsibilities:
+
+1. Connector midpoint stereotype labels (e.g. «import»).
+2. End-label role + «property» + multiplicity rendering.
+3. Geometry box parsing and position resolution.
+
+These change for different reasons:
+
+- Midpoint rendering changes when EA's connector stereotype
+  conventions change.
+- End-label rendering changes when role-name / multiplicity
+  rules change.
+- Box parsing changes when the QEA geometry format changes.
+
+MECE violation: the three concerns overlap inside one class. OCP
+violation: adding a new label kind (e.g. connector name above the
+midpoint) requires editing Labels rather than registering a new
+collaborator.
+
+## Fix
+
+Introduce a small LabelRenderer registry:
+
+```
+Ea::Svg::EaEmitter::Label
+  ├─ EndLabel    (role + «property» + mult at LLT/LRT boxes)
+  ├─ MidpointLabel (stereotype at path midpoint)
+  └─ Registry    (dispatch by relationship kind / connector flag)
+```
+
+`Labels#texts_for` becomes:
+
+```ruby
+def texts_for(connector)
+  points = waypoint_pairs(connector)
+  return [] if points.size < 2
+
+  Label::Registry.for(connector, model_index: model_index)
+                 .flat_map { |r| r.texts(connector, points) }
+end
+```
+
+Each renderer is independently testable. New label kinds are added
+by registering, not by editing Labels (OCP).
+
+## Acceptance
+
+- Three discrete classes; each has its own spec.
+- No behavior change (parity text overlap ≥ 87%).
+- Existing labels spec still passes.
+- New midpoint label spec covers the «import» path.

data/TODO.diagrams/20-visibility-glyph-font-encoding.md

@@ -0,0 +1,27 @@
+# 20 - Visibility Glyph Font (Plus Sign in Monospace)
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Three text-encoding fixes:
+1. Visibility marker now emits as `+ ` (with trailing space) —
+   matches EA's text content exactly.
+2. Namespace separator in type names converted to `::` (UML
+   standard) — `gml:CodeType` → `gml::CodeType`.
+3. Abstract class names no longer get double underscore when the
+   source name already starts with `_` (e.g. `_Feature` stays
+   `_Feature`, not `__Feature`).
+
+## Remaining gap
+
+Text counts overshoot ref on diagrams where the source classifier
+has more `ownedAttribute` entries than EA displays. EA truncates the
+visible attribute list (likely a per-diagram display filter or box-
+size fit), while we render every property. This is a content-
+filtering concern, not an encoding concern — deferred.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/elements.rb` — `abstract_name`,
+  `namespace_double_colon`, `split_visibility` updates

data/TODO.diagrams/21-aggregation-navigability-arrow.md

@@ -0,0 +1,21 @@
+# 21 - Aggregation Navigability Arrow at Part End
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`Markers#marker_specs` for Aggregation/Composition now returns TWO
+Specs:
+- Diamond polygon at whole end
+- Arrow path at part end
+
+Document interleaves line + diamond + arrow per aggregation
+connector (via `count_for` API + `pair_per_connector`).
+
+Waterway path count: 15 → 21 (ref=20, within ±1).
+Bridge polygon+path counts now within ±2 of ref.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/markers.rb` — `marker_specs` returns Array, `count_for` API
+- `lib/ea/svg/ea_emitter/document.rb` — `pair_per_connector` interleave

data/TODO.diagrams/21-auto-generated-legend-block.md

@@ -0,0 +1,65 @@
+# TODO-D 21: Auto-generated legend block
+
+## Problem
+
+EA renders a "凡例" (Legend) block in many diagrams that contain
+color-coded stereotype elements. The block contains:
+
+- A rounded-corner container rect (`rx=3`)
+- 3 color swatch rects (`17×17`)
+- A bold 12pt #003060 title "凡例"
+- Three 9pt #003060 lines naming the source packages
+
+Reference SVG example (EAID_0016F797):
+
+```xml
+<rect x="485" y="368" width="194" height="120" rx="3.00"/>
+<rect x="495" y="398" width="17" height="17"/>  <!-- swatch 1 -->
+<rect x="495" y="417" width="17" height="17"/>  <!-- swatch 2 -->
+<rect x="495" y="436" width="17" height="17"/>  <!-- swatch 3 -->
+<text x="546.00" y="387.00" font-weight:700 font-size:12pt>凡例</text>
+<text x="517.00" y="410.00">GMLに定義されたクラス</text>
+<text x="517.00" y="429.00">CityGMLに定義されたクラス</text>
+<text x="517.00" y="448.00">i-URに定義されたクラス</text>
+```
+
+The block is NOT modeled in the QEA schema. There is no "Legend"
+Object_Type, no t_lists row, no StyleEx flag tied to it.
+
+## Investigation Notes
+
+- 27 Note objects in the QEA, none contains "凡例".
+- 5 Text objects in the QEA, all empty Note field.
+- The legend titles and swatch colors vary per diagram but follow
+  a fixed vocabulary: GML, CityGML, i-UR.
+- The color swatches are the stereotype fill colors of elements
+  visible in the diagram (e.g. FFCFFF for CityGML, CCFFCC for GML).
+
+## Hypothesis
+
+EA's "Diagram Legend" feature is a built-in diagram decoration
+that auto-generates when:
+
+1. The diagram contains elements whose stereotype maps to a
+   known "package source" (GML, CityGML, i-UR).
+2. The user has placed a Legend UI element (which EA serializes
+   somewhere we haven't found yet — possibly t_image or a binary
+   blob).
+
+Without reverse-engineering EA.exe's legend code path or finding
+the serialization, replicating this verbatim is high-risk.
+
+## Status
+
+Deferred. Pinned in the parity report (TODO.diagrams/
+17-remaining-parity-gaps.md) as a known ~448-text gap.
+
+## Acceptance (when picked up)
+
+- Locate the legend serialization in the QEA (table + column).
+- Model `Ea::Model::Legend` with `position`, `title`, `entries`
+  (each entry: color + label).
+- Build `Ea::Svg::EaEmitter::Legend` renderer producing the
+  container rect + swatch rects + texts.
+- Specs cover: empty legend, single-entry, three-entry.
+- Parity text overlap climbs above 90%.

data/TODO.diagrams/22-ghost-element-discriminator.md

@@ -0,0 +1,57 @@
+# TODO-D 22: Ghost element discriminator
+
+## Problem
+
+EA renders some elements as "ghosts": smaller font (7pt), gray
+text (#595959), no attribute/operation/tag compartments. The
+discriminator is unclear.
+
+## Empirical Observations
+
+| Diagram            | Element                    | ObjectStyle                                          | Rendered as |
+|--------------------|----------------------------|------------------------------------------------------|-------------|
+| 位置図C0301        | _UrbanFunction             | NSL=0;LCol=-1;...font=Yu Gothic UI;...               | Full        |
+| 位置図C0301        | MultiSurface               | NSL=0;BFol=-1;...fontsz=0;bold=0;... (no font=)      | Ghost       |
+| CityGMLCore        | _Feature                   | NSL=0;BCol=-1;BFol=-1;LCol=-1;LWth=-1;fontsz=0;...   | Ghost       |
+| urf_4              | _UrbanFunction             | NSL=0;BFol=-1;LCol=-1;fontsz=0;bold=0;... (no font=) | **Full**    |
+| 都市計画決定情報   | _UrbanFunction             | NSL=0;LCol=-1;bold=0;... (no font=)                  | Ghost       |
+
+The presence or absence of `font=` is **not** the discriminator
+(urf_4 elements lack `font=` but render full attributes).
+
+`BCol` value is **not** the discriminator (urf_4 has explicit
+BCol=16777215; MultiSurface in 位置図C0301 has BCol=13434828).
+
+Classifier `package_id` vs diagram `package_id` is **not** the
+discriminator (urf_4 cross-package elements get full attrs;
+CityGMLCore cross-package elements get ghost).
+
+## Hypothesis To Test
+
+1. **Diagram-level "is reference" flag**: maybe EA marks diagrams
+   that only show snapshots of an external model. The discriminator
+   could be `t_diagram.SPT=1` (already 1 in all observed diagrams)
+   combined with another flag.
+
+2. **Element-level "Link" semantics**: maybe elements placed as
+   "links" rather than embedded get ghost styling. The QEA may
+   encode this in t_diagramlinks.Path or t_object.Documentation
+   style flags we haven't parsed.
+
+3. **t_objectstatistics or t_objectproperties**: an explicit "ghost
+   mode" tagged value.
+
+## Status
+
+Deferred. Without EA.exe disassembly or empirical testing inside
+the EA GUI, the rule cannot be confidently derived.
+
+## Acceptance (when picked up)
+
+- Open the QEA in EA GUI, toggle the "Link" vs "Embed" property
+  on an element, observe the rendered SVG, and identify the QEA
+  field that changes.
+- Implement a `ghost?` predicate on `Ea::Model::DiagramElement`
+  using the discovered field.
+- Wire through `Elements` emitter to apply ghost styling.
+- Specs cover both ghost and full paths.

data/TODO.diagrams/22-style-based-path-grouping.md

@@ -0,0 +1,28 @@
+# 22 - Style-Based Path Grouping
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`Connectors` emitter now supports `group_by_style:` constructor
+option. When true, consecutive connectors with the same line style
+are merged into a single `<g>` element with multiple `<path>` kids
+(matching EA's encoding for diagrams with many similarly-styled
+connectors).
+
+Default behavior remains per-entity grouping (one `<g>` per
+connector) to preserve z-order interleaving with markers.
+
+## Usage
+
+```ruby
+# Default: per-entity groups (current behavior)
+Connectors.new(diagram, canvas: canvas)
+
+# EA-style grouped:
+Connectors.new(diagram, canvas: canvas, group_by_style: true)
+```
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/connectors.rb` — `group_by_style` option + `grouped_groups`

data/TODO.diagrams/23-marker-polygon-deduplication.md

@@ -0,0 +1,47 @@
+# TODO-D 23: Marker polygon deduplication rules
+
+## Problem
+
+EA's rules for emitting polygon markers when multiple connectors
+share an endpoint are non-obvious.
+
+## Empirical Observations
+
+Aggregate across 188 reference SVGs:
+- Total polygons: 1485
+- Exact-duplicate polygons (same points string): **536** (36%)
+
+EA duplicates polygon markers in many cases but not always. The
+discriminator is unclear.
+
+## Experiments Tried
+
+| Strategy                    | Polygon delta | Within-tol |
+|-----------------------------|---------------|------------|
+| Anchor-based dedup (current)| -166 (-11.2%) | 123/188 (65.4%) |
+| No dedup                    | +257 (+17.3%) | 139/188 (73.9%) |
+| Exact-body dedup            | +247 (+16.6%) | 141/188 (75.0%) |
+
+Both "no dedup" and "exact-body dedup" improve within-tolerance
+diagram count (+13%) but introduce polygon overshoot. Anchor-based
+dedup has best polygon delta but lower diagram-tol rate.
+
+## Hypothesis To Test
+
+EA likely has per-marker-per-connector emission for `Path=`-routed
+connectors (each visible link emits its own markers) but deduplicates
+markers that share an anchor AND belong to connectors sharing a
+common segment.
+
+The QEA stores a `Path=` field on t_diagramlinks; connectors that
+share the same visual path are co-rendered. We currently treat
+each t_diagramlinks row independently.
+
+## Acceptance (when picked up)
+
+- Correlate polygon duplicates with shared `Path=` values.
+- Implement per-diagram `grouped:` mode selection in Markers.
+- Specs cover: distinct anchors (no dedup), shared anchor + shared
+  path (dedup), shared anchor + distinct path (no dedup).
+- Polygon delta within ±20 (currently -166).
+- Within-tolerance diagrams ≥ 75% (currently 65.4%).

data/TODO.diagrams/23-multiplicity-label-positioning.md

@@ -0,0 +1,29 @@
+# 23 - Diagram-Level Multiplicity Label Positioning
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Refactored `Ea::Svg::EaEmitter::Labels` to emit per-end role name +
+multiplicity using LLB (left label box) / LLT (left label text) and
+RLB / RLT offsets from the connector geometry.
+
+Uses UML convention: the role visible at one end of the connector is
+the property owned by the OPPOSITE classifier. So LLT (near source)
+shows the target-end property; RLT (near target) shows the source-
+end property.
+
+Each label emits as TWO `<text>` elements matching EA's encoding:
+one for the role name (`+roleName`) and one for the multiplicity
+(`0..1`).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/labels.rb` — full rewrite with model_index,
+  association_ends, label_position, role_text, multiplicity_text
+- `lib/ea/svg/ea_emitter/document.rb` — passes `model_index` to Labels
+
+## Outcome metrics
+
+Text count mean abs diff dropped from 20 → 14 across 185 diagrams.
+Waterway: 92 → 103 (ref=113). CityFurniture: 24 → 30 (ref=34).

data/TODO.diagrams/24-marker-anchor-structural.md

@@ -0,0 +1,35 @@
+# TODO-D 24: Track marker anchors structurally
+
+## Problem
+
+`Ea::Svg::EaEmitter::Markers#anchor_key` parses the SVG string the
+class itself just emitted in order to deduplicate entries by their
+anchor point:
+
+```ruby
+def anchor_key(body)
+  match = body.match(/polygon points="(-?[\d.]+)\s+(-?[\d.]+)|path d="M (-?[\d.]+)\s+(-?[\d.]+)/)
+  return body unless match
+  ...
+end
+```
+
+This is fragile:
+
+- Round-trip through string parsing for data we already had
+  structurally.
+- Regex assumes EA's exact SVG attribute ordering and whitespace.
+- Hard to test in isolation (must build the body string first).
+
+## Fix
+
+Add `anchor` to the `Entry` struct. Capture it when the entry is
+built (we already have `tip` at that point). Dedup on
+`Entry#anchor` rather than re-parsing the body.
+
+## Acceptance
+
+- `Entry` struct carries `[x, y]` anchor.
+- `anchor_key` method removed; dedup uses `Entry#anchor` directly.
+- Markers specs continue to pass.
+- Parity polygon delta unchanged.

data/TODO.diagrams/24-track-marker-anchors-structurally.md

@@ -0,0 +1,66 @@
+# TODO-D 24: Track marker anchors structurally (DONE)
+
+## Before
+
+`Markers#anchor_key` parsed the rendered SVG string with regex to
+extract the marker's anchor coordinates:
+
+```ruby
+def anchor_key(body)
+  match = body.match(/polygon points="(-?[\d.]+)\s+(-?[\d.]+)|path d="M (-?[\d.]+)\s+(-?[\d.]+)/)
+  return body unless match
+  x = (match[1] || match[3]).to_f.round
+  y = (match[2] || match[4]).to_f.round
+  [x, y]
+end
+```
+
+That mixes "data" (the anchor) with "presentation" (the rendered
+string), and it parses the same SVG twice. Re-introducing the
+anchor as a Ruby value fixes both.
+
+## After
+
+`Markers::Entry` is now a Struct that carries the anchor alongside
+the body, with hash/eql? defined so `Array#uniq` collapses by
+anchor without touching the SVG:
+
+```ruby
+Entry = Struct.new(:style_key, :body, :anchor, keyword_init: true) do
+  def hash
+    anchor.hash
+  end
+
+  def eql?(other)
+    other.is_a?(Entry) && anchor == other.anchor
+  end
+end
+```
+
+`entries_for` computes the anchor once when building the Entry:
+
+```ruby
+def anchor_for(spec)
+  tx, ty = translate_point(spec.anchor)
+  [tx.round, ty.round]
+end
+```
+
+## Benefits
+
+- **Performance**: one anchor computation per marker instead of
+  a regex match per dedup pass.
+- **Type safety**: anchor is a `[Integer, Integer]` pair, not a
+  parsed fragment of a String.
+- **Encapsulation**: rendered SVG never re-parsed.
+- **Testability**: `Entry#eql?` is unit-testable in isolation.
+
+## Tests
+
+- `spec/ea/svg/ea_emitter/markers_entry_spec.rb` covers anchor
+  equality, deduplication, and false-positive guards.
+
+## Bench
+
+Unchanged: rect -221, path -280, polygon -6, text -601,
+overlap 64.5%. The refactor is behavior-preserving.