ea 0.4.0 → 0.5.1

data/TODO.diagrams/07-text-content-fidelity.md

@@ -0,0 +1,65 @@
+# TODO-D 07 - Full text content fidelity
+
+## Status: PARTIAL (62% overlap) (2026-07-26)
+
+## Current state
+
+Text overlap (Jaccard index of text content sets between our SVG
+and reference SVG):
+
+- Average across 185 plateau diagrams: **62%**
+- Best diagrams: ~95%
+- Worst diagrams: ~20%
+
+## What's working
+
+- Classifier names and stereotypes render correctly when the
+  element is placed on the diagram.
+- Attribute text matches when the element has Tag=0 (no tagged
+  values compartment).
+- Visibility prefixes ("+ ", "- ") match.
+- Multiplicity brackets match.
+
+## What's still off
+
+### 1. Tagged value visibility (mostly fixed, edge cases remain)
+Reference SVGs don't render the "tags" header compartment except
+on 2 diagrams. Our Tag-flag gating brought text overlap from 41%
+to 62%. Remaining misses are likely from elements where the
+`Tag=1` flag is set but the reference still doesn't render tags
+— possibly tied to stereotype source (profile-applied vs
+user-defined tagged values).
+
+### 2. Qualified name vs simple name
+Reference uses qualified names like
+`uro::TrafficVolumeAttribute`. Our output sometimes uses the
+short name only. The qualified_name attribute is set on the
+Classifier model, but the renderer doesn't always pick it up
+correctly when the element is placed on a sub-package diagram.
+
+### 3. Attribute ordering
+Within a classifier's attribute compartment, EA sorts attributes
+by some criteria (possibly visibility then alphabetical). Our
+ordering follows the XMI's `ownedAttribute` order, which may
+differ.
+
+### 4. Attribute visibility color
+Reference uses different fill colors for public/protected/private
+attributes (`#66413F` for some, `#595959` for others). Our
+renderer uses a single text color from the theme.
+
+## Path to 100% text overlap
+
+1. Characterize the tagged value visibility rule by examining
+   which elements with `Tag=1` still don't render tags in
+   reference (estimated 5-10 diagrams).
+
+2. Always use `classifier.qualified_name` for the header label
+   (currently mixed).
+
+3. Sort attributes by visibility prefix, then alphabetical.
+
+4. Apply theme.color_for_attribute_visibility for attribute text.
+
+Each of these is a separate fix. None require architectural
+changes.

data/TODO.diagrams/08-qea-direct-pipeline.md

@@ -0,0 +1,46 @@
+# TODO-D 08-11 - QEA-direct pipeline
+
+## Status: COMPLETE (2026-07-27)
+
+## What was wired
+
+1. **TODO-D 08**: QEA DiagramBuilder propagates StyleEx to
+   Diagram.style_ex. Theme=:119 is now correctly detected from QEA.
+
+2. **TODO-D 09**: IdNormalizer.to_eaid converts `{GUID}` to
+   `EAID_<guid-with-underscores>` for matching reference SVG
+   filenames. The QEA stores diagram GUIDs in braces-dashes form;
+   the reference SVGs use the EAID_ underscore form.
+
+3. **TODO-D 10**: New QEA NoteBuilder parses t_object rows with
+   object_type="Note" or "Text". These render as Package-shaped
+   diagram boxes (not dog-eared Notes — QEA's "Note" type is a
+   diagrammatic Package-shape box for free text, distinct from
+   XMI's uml:Note).
+
+   Also: connector_type from t_connector.Type is now propagated
+   to DiagramConnector so Marker::Diamond matches Aggregation
+   and Composition (was being dropped, all connectors fell back
+   to Association).
+
+4. **TODO-D 11**: spec/ea/svg/qea_regression_spec.rb renders all
+   188 diagrams directly from the QEA against reference SVGs.
+   Passes at the 60 percent within-tolerance threshold.
+
+## Parity delta from QEA-direct fixes
+
+| Metric | Before | After |
+|---|---|---|
+| Polygon delta | n/a (was reading XMI) | -166 (was -842 at start) |
+| Path delta | n/a | -181 |
+| Text overlap avg | 10% (initial QEA-direct) | 56% |
+| Within tolerance | 60.6% | 65.4% |
+
+## Bonus fixes shipped alongside
+
+- ClassifierBuilder no longer prepends package name to
+  qualified_name (QEA t_object.Name already includes the prefix).
+- HeaderLines no longer renders fallback stereotype labels.
+- AttributeRenderer no longer double-colons type names.
+- bounds_from_rect uses min/max of rect values (QEA stores rect
+  with recttop > rectbottom).

data/TODO.diagrams/12-connector-labels.md

@@ -0,0 +1,40 @@
+# TODO-D 12 - Connector role/multiplicity labels
+
+## Status: COMPLETE (2026-07-27)
+
+## What changed
+
+Labels renderer refactored to support both XMI and QEA paths:
+
+1. **Property lookup (XMI path)**: When the Association's
+   source_id/target_id reference Property IDs, look them up and
+   render the role name + multiplicity from the Property fields.
+
+2. **Association fields (QEA path)**: Fall back to the
+   Association's own source_role_name, target_role_name,
+   source_multiplicity_lower/upper, target_multiplicity_lower/upper
+   fields. These are populated by QEA's t_connector.sourcerole/
+   destrole/sourcecard/destcard columns.
+
+3. **Default label offset**: When label_boxes aren't populated
+   (QEA path — the geometry parser doesn't yet extract them),
+   use a default offset (anchor + 5, -10) so labels render near
+   the connector endpoints rather than being silently dropped.
+
+## Acceptance
+
+QEA-direct parity measurement:
+
+| Metric | Before | After |
+|---|---|---|
+| Text delta vs ref | -2728 (14% under) | -883 (5% under) |
+| Text overlap avg | 56.0% | 62.8% |
+
+## Remaining
+
+- QEA t_diagramlinks.Geometry parser doesn't extract LLB/LRB
+  boxes. Adding that would let labels render at EA's recorded
+  pixel positions rather than the default offset.
+- The XMI-encoded `<text>` ordering within Labels is still
+  suboptimal — EA emits role name and multiplicity in a single
+  `<g>` block, we emit each as a separate text element.

data/TODO.diagrams/12-per-entity-svg-layer-ordering.md

@@ -0,0 +1,24 @@
+# 12 - Per-Entity SVG Layer Ordering
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Restructured `Ea::Svg::EaEmitter::Document` to emit a flat sequence
+of top-level `<g>` elements matching EA's per-entity layering:
+
+- `Elements#groups` returns Array of per-element `<g>` blocks
+  (shape → header → divider → attrs)
+- `Connectors#groups` returns Array of one `<g>` per connector line
+- `Markers#groups` returns Array of one `<g>` per connector marker
+- `Document#connector_layers` interleaves line + marker per connector
+
+Verified on Waterway: 50 top-level `<g>` (ours) vs 47 (ref) — the
+3-group delta is due to the spurious frame element (TODO 14).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/document.rb` — interleaves line/marker per connector
+- `lib/ea/svg/ea_emitter/elements.rb` — `groups` method, per-element arrays
+- `lib/ea/svg/ea_emitter/connectors.rb` — `groups` method, one `<g>` per connector
+- `lib/ea/svg/ea_emitter/markers.rb` — `groups` method, one `<g>` per marker

data/TODO.diagrams/13-marker-polygon-vs-path-dispatch.md

@@ -0,0 +1,20 @@
+# 13 - Marker Encoding: Polygon vs Path by Shape
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Refactored `Ea::Svg::EaEmitter::Markers` to dispatch marker shape
+via a `Spec` value object. Each marker emits the correct element type:
+
+- Diamond (Aggregation/Composition) → `<polygon>` 4 points
+- Open triangle (Generalization/Realization/Dependency) → `<polygon>` 3 points, white fill
+- Filled arrow (Association navigability) → `<path d="M .. L .. L .."/>` 3 points
+
+Marker placement is direction-aware: "Destination -> Source" flips
+which end holds the marker.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/markers.rb` — Spec struct + dispatch
+- `spec/ea/svg/ea_emitter/markers_spec.rb` — updated to reflect arrow emission

data/TODO.diagrams/13-per-text-type-font-sizes.md

@@ -0,0 +1,33 @@
+# TODO-D 13 - Per-text-type font sizes
+
+## Status: COMPLETE (2026-07-27)
+
+## Context
+
+Reference SVGs use different font sizes for different text types:
+- 9pt for classifier compartments (header, attributes, operations,
+  enumeration literals, tagged values)
+- 7pt for diagram-level text (frame label, swimlane names)
+- 12pt for some classifier names (rare)
+
+Theme :119 specifies font_size=7pt — that's the DIAGRAM-LEVEL font
+size, not the element-level default. Element compartment text uses
+9pt regardless of theme.
+
+## What changed
+
+- `FontResolver::DEFAULT_ELEMENT_FONT_SIZE = 9` — replaces the
+  previous default of 13 (which was the Yu Gothic UI locale default)
+- `FontResolver#size_for` no longer falls back to `theme.font_size`
+  for elements — only diagram-level text uses theme font size
+- `HeaderRenderer` and `AttributeRenderer` gain `size_unit:`
+  parameter (defaults to `"pt"`) and propagate it to TextRenderer
+- `Elements#groups_for` reads `size_unit` from FontResolver and
+  passes through to all renderers
+
+## Acceptance
+
+- Reference text uses `font-size:9pt` for classifier compartments
+- Our text now emits `font-size:9pt` (was `font-size:7px`)
+- Text overlap metric unchanged (counts content, not formatting)
+- 1612 specs pass

data/TODO.diagrams/14-center-header-text.md

@@ -0,0 +1,33 @@
+# TODO-D 14 - Center classifier header text
+
+## Status: COMPLETE (2026-07-27)
+
+## Context
+
+EA centers stereotype and classifier-name text horizontally within
+the element bounds. SVG `<text x=>` is the LEFT edge of the text,
+not the center, so we need to compute:
+
+  left_edge = bounds.center_x - text_width / 2
+
+Our previous code emitted `x = bounds.center_x` directly, which
+placed the LEFT EDGE at the center — making all text appear
+right-of-center.
+
+## What changed
+
+`HeaderRenderer.center_x_for(text, bounds, size)` computes the
+left edge from a text-width approximation:
+
+  text_width = text.length * size * 0.55
+
+The factor 0.55 approximates average Carlito character width as a
+fraction of point size. Not pixel-perfect (EA uses GDI text
+metrics) but visually centered.
+
+## Acceptance
+
+- Stereotype label now visually centered in element box
+- Classifier name now visually centered
+- Close to reference x positions (within ~5px due to text-width
+  approximation)

data/TODO.diagrams/14-filter-diagram-frame-elements.md

@@ -0,0 +1,18 @@
+# 14 - Filter Diagram-Frame / Note Elements
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Added `Elements#frame_element?` predicate that skips elements
+matching the diagram-frame pattern:
+- `background_color == -1` (sentinel for "no fill / default"), AND
+- Classifier name is nil/empty, AND
+- Classifier has no properties
+
+Verified: Waterway top-level `<g>` count drops 50→47, rect count
+drops 10→9 — both now match EA reference exactly.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/elements.rb` — `frame_element?` predicate

data/TODO.diagrams/15-deep-dead-code-audit.md

@@ -0,0 +1,47 @@
+# TODO-D 15 - Deep dead code audit
+
+## Status: COMPLETE (2026-07-27)
+
+## Audit findings
+
+All production subsystems in `lib/ea/` are actively used:
+
+| Subsystem | Used by | Status |
+|---|---|---|
+| `Ea::Model` | All adapters and renderers | KEEP |
+| `Ea::Sources::Qea` | `Ea.parse`, `Ea::Sources::Qea::Adapter.from_path` | KEEP |
+| `Ea::Sources::Xmi` | `Ea::Sources::Xmi::Adapter.from_path` | KEEP |
+| `Ea::Svg::EaEmitter` | `ea svg` CLI command | KEEP |
+| `Ea::Theme` | Diagram.theme resolution | KEEP |
+| `Ea::Diagram::DisplayConfig` | `Diagram#display_config` | KEEP |
+| `Ea::Qea` (SQLite layer) | `Ea::Sources::Qea::*` adapters | KEEP |
+| `Ea::Xmi` | `Ea::Sources::Xmi::*` adapters | KEEP |
+| `Ea::Spa` | `ea spa` CLI command | KEEP |
+| `Ea::Transformers` | `ea convert` CLI command | KEEP |
+| `Ea::Bridge` | `Ea::Transformations.to_uml` | KEEP |
+| `Ea::Transformations` | `RepositoryBuilder` for bridge CLI | KEEP |
+
+## Code quality audit
+
+| Rule | Status |
+|---|---|
+| No `send` to call private methods | CLEAN |
+| No `instance_variable_set`/`get` | CLEAN (only mentioned in a comment) |
+| No `respond_to?` for type checks | CLEAN (replaced with `is_a?` earlier) |
+| No `require_relative` for library code | CLEAN (one in `lib/ea.rb` for VERSION — standard gemspec pattern) |
+| autoload for all internal loading | CLEAN |
+
+## Architecture observations
+
+The codebase follows OCP well:
+- `Marker::Kind` subclasses registered via `Marker::Registry.register`
+- `Theme::Definition` immutable value object with `#with` for variants
+- `Theme::Registry` auto-loads from `config/themes/*.yml`
+- `Element::*Renderer` classes are independent — adding a new
+  compartment type doesn't modify existing renderers
+
+## DRY
+
+Found one minor duplication: `Labels` and `AttributeRenderer` both
+have text-emission logic. Consolidated into shared `TextRenderer`
+calls. No further DRY violations observed.

data/TODO.diagrams/15-per-element-font-from-style.md

@@ -0,0 +1,24 @@
+# 15 - Per-Element Font from Style
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Added `Ea::Svg::EaEmitter::FontResolver` that resolves font family +
+size + weight + style per element, using EA's fallback chain:
+
+1. Element-level `font_family` / `font_size` (set from EA's
+   `font=NAME;fontsz=PCT` style fields via ExtensionStyleParser)
+2. Diagram-level default (most common non-nil value across elements)
+3. Module default (`Yu Gothic UI`, `13`)
+
+`Elements` emitter delegates font resolution to FontResolver so the
+fallback rule lives in one place (MECE).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/font_resolver.rb` — new resolver
+- `lib/ea/svg/ea_emitter.rb` — autoload registration
+- `lib/ea/svg/ea_emitter/elements.rb` — uses FontResolver
+- `spec/ea/svg/ea_emitter/font_resolver_spec.rb` — 9 specs covering
+  explicit, fallback, and empty-diagram cases

data/TODO.diagrams/16-canvas-marker-extent.md

@@ -0,0 +1,30 @@
+# 16 - Canvas Bounds Include Marker Extent
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`Canvas.from` now extends the points list with `MARKER_EXTENT=15`
+padding around each connector's source and target waypoints. This
+prevents markers (diamonds, triangles, arrows) from being clipped
+when they project beyond element bounds.
+
+For Waterway this didn't change the canvas size (markers fit within
+existing element bounds), but for diagrams where arrows extend below
+or beside elements, the canvas now grows accordingly.
+
+## Remaining diff
+
+Waterway height: ours 869 vs ref 892 (23 px short). Root cause:
+EA's renderer uses `image_bounds` (with 12 px image padding) for
+certain elements while we use logical `bounds`. The 23 px diff
+matches the difference between logical and image_bounds for the
+lowest element (FacilityIdAttribute: logical bottom=895, image
+bottom=918). To close this fully we'd need to compute canvas from
+image_bounds union (matching EA's behavior), but this would also
+require translating elements by image_bounds rather than logical
+bounds — a larger change deferred to TODO 18.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/canvas.rb` — `marker_extents` + concat into points

data/TODO.diagrams/16-document-remaining-parity-gaps.md

@@ -0,0 +1,91 @@
+# TODO-D 16 - Document all remaining parity gaps
+
+## Status: LIVING DOCUMENT (2026-07-27)
+
+## Current parity (QEA-direct, 188 diagrams)
+
+| Metric | Value |
+|---|---|
+| Within shape-count tolerance | 123/188 (65.4%) |
+| Text overlap avg | 62.8% |
+| Polygon delta | -166 |
+| Path delta | -181 |
+| Text delta | -883 |
+| Rect delta | -460 |
+
+## Byte-level diff status (maintenance diagram)
+
+The simplest diagram (`maintenance`, 1 classifier) now matches
+reference byte-for-byte on:
+
+- Canvas dimensions (254x177) ✓
+- Element position (35, 40) ✓
+- Background rect dimensions ✓
+- Frame border path coordinates ✓
+
+Remaining byte-level differences on maintenance:
+
+### 1. Build ID
+- Ours: `Build: 1628`
+- Ref: `Build: 1624`
+
+The QEA was authored with build 1628 (newer). The reference SVGs
+were exported with build 1624. Either change the BUILD_ID constant
+or accept the difference.
+
+### 2. Frame tab width
+- Ours: `points="6 26 135 26 148 13 148 6 6 6 6 26"` (width=129)
+- Ref:  `points="6 26 86 26 99 12 99 6 6 6 6 26"` (width=80)
+
+EA calculates the tab width from GDI text metrics on the label
+"class maintenance". Our calculation uses `label.length * 7 + 10`
+which overshoots. Need a better text-width approximation, OR
+match EA's hardcoded minimum (80px).
+
+### 3. textLength attribute
+- Ours: `textLength="65"`
+- Ref:  `textLength="73"`
+
+Same root cause as #2 — text-width approximation differs from
+GDI metrics.
+
+### 4. Whitespace formatting
+- Ours: extra blank lines between `<g>` blocks
+- Ref:  no blank lines, tabs for indentation
+
+Cosmetic only — doesn't affect rendering.
+
+## Aggregate parity gaps (across 188 diagrams)
+
+### Polygon under-rendering (-166)
+Source-side diamond markers on Aggregation connectors. The diamond
+anchor positions drift from EA because connector SX/SY/EX/EY
+interpretation isn't exact. Markers render but at slightly wrong
+positions, breaking the per-anchor dedup match.
+
+### Path under-rendering (-181)
+EA combines connector line + arrow head into one `<path>` with
+multiple `M` sub-paths. We emit them as separate paths. Restructure
+`Connectors` renderer to emit combined paths per connector.
+
+### Text under-rendering (-883)
+Three categories:
+1. Connector label positions (we use default offset; EA records
+   exact LLB/LRB boxes in t_diagramlinks.Geometry)
+2. Attribute defaults (e.g. `lod: integerBetween0and4 = 1` — we
+   drop the `= default_value` part)
+3. Stereotype-tagged-value text (we render the «property»
+   stereotype label on some diagrams where ref doesn't)
+
+### Rect under-rendering (-460)
+Mostly classifier-box compartment rects that EA emits as inner
+rects (not paths) for some diagram configurations. Also legend
+swatches inside Note elements. Not yet investigated thoroughly.
+
+## Priority order for closing remaining gaps
+
+1. **Combined connector paths** — fixes path -181, no architectural change
+2. **QEA geometry parser for LLB/LRB** — fixes most of text -883
+3. **Attribute default value rendering** — fixes some text delta
+4. **Frame tab width calculation** — fixes byte-diff on simple diagrams
+5. **Rect inner-compartment rendering** — fixes rect -460

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.