ea 0.4.0 → 0.5.0

data/TODO.fixup/43-colorresolver-unification.md

@@ -0,0 +1,24 @@
+# 43 - Unify Color Computation (ColorResolver)
+
+## Status: DONE (2026-07-26)
+
+## Outcome
+
+New `Ea::Svg::EaEmitter::ColorResolver` is single source of truth
+for fill + stroke color decisions. Precedence chain:
+1. element BCol (when present and not sentinel)
+2. theme per-type pastel (when theme is themed)
+3. stereotype color (via stereotype_resolver)
+4. default fill
+
+Same chain for stroke (LCol → theme.border → default).
+
+Replaces 4 inline methods in Elements (resolve_fill, theme_fill_for,
+fill_for_classifier, primary_stereotype).
+
+## Files changed
+
+- lib/ea/svg/ea_emitter/color_resolver.rb — NEW
+- lib/ea/svg/ea_emitter.rb — autoload
+- lib/ea/svg/ea_emitter/elements.rb — delegate to ColorResolver
+- spec/ea/svg/ea_emitter/color_resolver_spec.rb — 10 specs

data/TODO.fixup/44-theme-aware-textrenderer.md

@@ -0,0 +1,17 @@
+# 44 - Theme-Aware TextRenderer
+
+## Status: ANALYZED (2026-07-26, closed)
+
+## Decision
+
+TextRenderer already accepts per-call fill/weight/size_unit
+overrides. Callers (HeaderRenderer, AttributeRenderer, etc.)
+can pass theme-derived values explicitly. Adding theme
+awareness inside TextRenderer would duplicate the FontResolver
+logic — better to keep TextRenderer stateless.
+
+Theme values flow through FontResolver which is now theme-aware
+(fixup 45). HeaderRenderer etc. can consult FontResolver for
+weight/size_unit/fill and pass to TextRenderer.
+
+Closing — current design is correct MECE separation.

data/TODO.fixup/45-theme-aware-fontresolver.md

@@ -0,0 +1,22 @@
+# 45 - Theme-Aware FontResolver
+
+## Status: DONE (2026-07-26)
+
+## Outcome
+
+FontResolver constructor accepts optional `theme:` param.
+Precedence chain:
+1. element.font_family (per-element override)
+2. theme.font_family (when theme is themed)
+3. diagram-default (most common element font)
+4. locale fallback (Calibri 10)
+
+Same for size. Added `size_unit_for` and theme-aware weight_for.
+
+Elements passes theme via `FontResolver.new(diagram, theme: theme)`.
+
+## Files changed
+
+- lib/ea/svg/ea_emitter/font_resolver.rb — theme param + size_unit
+- lib/ea/svg/ea_emitter/elements.rb — pass theme to FontResolver
+- spec/ea/svg/ea_emitter/font_resolver_spec.rb — theme :119 specs

data/TODO.fixup/46-style-parameterized-by-theme.md

@@ -0,0 +1,21 @@
+# 46 - Style Constants Parameterized by Theme
+
+## Status: ANALYZED (2026-07-26, deferred)
+
+## Decision
+
+Current Style constants (CONNECTOR_LINE, DIAMOND_FILLED, etc.)
+bake in stroke-width=2. Making them theme-parameterized would
+require threading Theme through Connectors/Markers — significant
+plumbing for marginal benefit since:
+- Plateau (default theme) is the primary use case and uses sw=2
+- Theme :119 diagrams use the same constants but render via
+  Elements (which already uses theme.stroke_width)
+
+The Connectors/Markers layer doesn't yet need theme support
+since plateau parity is the primary target. Deferred until
+theme-aware connector rendering is required.
+
+## Files changed
+
+None.

data/TODO.fixup/47-canvas-frame-inset.md

@@ -0,0 +1,19 @@
+# 47 - Canvas Frame Inset
+
+## Status: ANALYZED (2026-07-26, deferred)
+
+## Decision
+
+When frame is enabled, elements can overlap the frame border
+(6px inset). This is a real issue but only affects the simple/
+basic test diagrams (where frame is opt-in via frame: true).
+
+Plateau (frame disabled) is unaffected.
+
+The fix would require BoundsCalculator to add 6px to all
+elements when frame is enabled — non-trivial plumbing. Deferred
+until frame auto-detection is implemented.
+
+## Files changed
+
+None.

data/TODO.fixup/48-background-rect-format.md

@@ -0,0 +1,15 @@
+# 48 - Background Rect Format Match
+
+## Status: ANALYZED (2026-07-26, verified correct)
+
+## Finding
+
+Verified Background.render output against EA reference:
+  EA:    <g style="fill:#FFFFFF;fill-opacity:1.00;">
+  Ours:  <g style="fill:#FFFFFF;fill-opacity:1.00;">
+
+MATCH. No change needed.
+
+## Files changed
+
+None.

data/TODO.fixup/49-all-samples-integration-test.md

@@ -0,0 +1,17 @@
+# 49 - Render All Sample Diagrams Integration Test
+
+## Status: DEFERRED
+
+## Decision
+
+The visual_regression_spec.rb already renders many diagrams
+from the plateau XMI. Adding a new spec for examples/exports/*
+would duplicate the test surface without adding new coverage
+until QEA loader is wired (for style_ex).
+
+Deferred until QEA wiring or when specific sample diagrams
+need targeted testing.
+
+## Files changed
+
+None.

data/TODO.fixup/50-svg-emitter-architecture-docs.md

@@ -0,0 +1,33 @@
+# 50 - SVG Emitter Architecture Documentation
+
+## Status: ANALYZED (2026-07-26)
+
+## Architecture summary
+
+    Document
+      └─ LayerSequencer (frame?, theme via diagram.style_ex)
+           ├─ Background
+           ├─ DiagramFrame (opt-in)
+           ├─ Elements → Element::* compartment renderers
+           │    ├─ ShapeRenderer → TextRenderer
+           │    ├─ HeaderRenderer → TextRenderer
+           │    ├─ DividerRenderer
+           │    ├─ AttributeRenderer → TextRenderer
+           │    ├─ OperationRenderer → TextRenderer
+           │    └─ EnumerationLiteralRenderer → TextRenderer
+           ├─ Connectors → Layer
+           ├─ Markers → Marker::Registry (OCP) → Layer
+           └─ Labels → TextRenderer
+
+    Cross-cutting:
+      Canvas (value object, translate_x/y)
+      BoundsCalculator (3 source strategies)
+      ColorResolver (BCol → theme → stereotype → default)
+      FontResolver (element → theme → diagram → locale)
+      Theme / ThemeRegistry (OCP)
+      TextRenderer (decimal coords + rotation transform)
+      Style (centralized constants)
+
+## Files changed
+
+None — documented in TODO.

data/TODO.fixup/51-promote-theme-to-ea-namespace.md

@@ -0,0 +1,28 @@
+# 51 - Promote Theme to Ea::Theme Top-Level Namespace
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Theme is currently `Ea::Svg::EaEmitter::Theme` — buried inside the
+SVG emitter. But Theme is a DOMAIN concept (visual style), not
+rendering-specific. Other consumers (HTML docs, image rendering,
+documentation generation) will also need themes.
+
+The current placement violates MECE: Theme logic is mixed with
+SVG rendering concerns.
+
+## What needs to change
+
+1. New `Ea::Theme` module at top level (in `lib/ea/theme.rb`)
+2. Move `Ea::Svg::EaEmitter::Theme` → `Ea::Theme::Definition`
+3. Move `Ea::Svg::EaEmitter::ThemeRegistry` → `Ea::Theme::Registry`
+4. Move `Ea::Svg::EaEmitter::ThemeColors` → merge into Definition
+5. Backward-compat aliases in EaEmitter (temporary)
+
+## Acceptance
+
+- Ea::Theme module exists with autoloads for Definition, Registry
+- Ea::Svg::EaEmitter::Theme aliases to Ea::Theme::Definition
+- All existing specs pass
+- New spec verifies the namespace move

data/TODO.fixup/52-theme-definition-integrated-fills.md

@@ -0,0 +1,26 @@
+# 52 - Theme::Definition with Integrated Fills
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+`ThemeColors` is a separate module mapping classifier types to
+fill colors. This is a Theme concern — the colors ARE part of the
+theme definition. Currently they're scattered across two modules.
+
+## What needs to change
+
+1. `Ea::Theme::Definition` gains a `fills` attribute (Hash:
+   classifier class name → hex color)
+2. `#fill_for(classifier)` method on Definition returns the
+   per-type fill or nil
+3. `#with(**overrides)` method returns a new Definition with the
+   specified fields overridden (immutable editing pattern)
+4. Built-in :default and :119 themes include their fills inline
+
+## Acceptance
+
+- Definition has `fills` Hash attribute
+- Definition#fill_for(classifier) returns correct color per type
+- Definition#with(**overrides) returns new Definition
+- All existing specs pass

data/TODO.fixup/53-theme-registry-yaml-loading.md

@@ -0,0 +1,50 @@
+# 53 - Theme::Registry with YAML Loading
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Current `ThemeRegistry` has built-in themes hard-coded as Ruby
+constants. Like `stereotype_colors.yml`, themes should be
+externalized to YAML files for easy editing.
+
+## What needs to change
+
+1. `Ea::Theme::Loader` loads a YAML file into a Definition
+2. `Ea::Theme::Registry.load_dir(path)` loads all themes from
+   a directory (one YAML file per theme)
+3. `config/themes/` directory holds theme definition files:
+   - `default.yml` — no theme (uses element-stored values)
+   - `119.yml` — Carlito 7pt, gray text, purple-gray borders
+4. Registry auto-loads from `config/themes/` on first access
+
+## YAML format
+
+```yaml
+id: "119"
+name: EA White Theme
+font:
+  family: Carlito
+  size: 7
+  unit: pt
+text:
+  color: "#595959"
+  weight_normal: 0
+  weight_bold: 700
+border:
+  color: "#9A8484"
+  stroke_width: 1
+fills:
+  Klass: "#FDFAF7"
+  Interface: "#F1ECFA"
+  DataType: "#FAF9E6"
+  Enumeration: "#E8FDE3"
+  PrimitiveType: "#FAF9E6"
+```
+
+## Acceptance
+
+- config/themes/default.yml and 119.yml exist
+- Registry.load_dir loads them
+- YAML format matches Definition fields
+- New spec covers YAML loading

data/TODO.fixup/54-diagram-theme-api.md

@@ -0,0 +1,50 @@
+# 54 - Diagram#theme and #theme= API
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Currently `Diagram` has `theme_id` (string from style_ex) but
+no way to get or set the resolved Theme Definition object. Users
+cannot:
+- Get the active theme: `diagram.theme`
+- Set a theme: `diagram.theme = :119`
+- Override theme on a specific diagram: `diagram.theme = custom_def`
+
+## What needs to change
+
+1. `Diagram#theme` — returns resolved Definition:
+   - theme_override if set
+   - Registry.lookup(theme_id) otherwise
+   - Registry::DEFAULT if neither
+2. `Diagram#theme=(value)` — accepts:
+   - `Ea::Theme::Definition` instance → sets theme_override
+   - String ID (":119") → sets theme_id, clears override
+   - Symbol ID (:119) → sets theme_id, clears override
+3. `Diagram#theme_override` — stores explicit Definition
+4. JSON mapping for theme_id and theme_override
+
+## Usage
+
+```ruby
+# Read theme
+diagram.theme  # → Ea::Theme::Definition
+
+# Set by ID
+diagram.theme = :119
+diagram.theme = ":119"
+
+# Set custom definition
+diagram.theme = Ea::Theme::Definition.new(id: "custom", ...)
+
+# Edit existing theme (immutable → new instance)
+diagram.theme = diagram.theme.with(text_color: "#FF0000")
+```
+
+## Acceptance
+
+- Diagram#theme returns Definition
+- Diagram#theme= accepts Definition, String, Symbol
+- Diagram#theme_override stores explicit Definition
+- JSON round-trip preserves theme_id and theme_override
+- New specs cover all access patterns

data/TODO.fixup/55-update-eaemitter-to-ea-theme.md

@@ -0,0 +1,23 @@
+# 55 - Update EaEmitter to Use Ea::Theme Namespace
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+After promoting Theme to Ea::Theme (TODO 51), the EaEmitter must
+reference the new paths. ColorResolver, FontResolver, Elements,
+and LayerSequencer all reference `ThemeRegistry.lookup(diagram.theme_id)`.
+
+## What needs to change
+
+1. All `Ea::Svg::EaEmitter::ThemeRegistry` → `Ea::Theme::Registry`
+2. All `Ea::Svg::EaEmitter::Theme` → `Ea::Theme::Definition`
+3. `Diagram#theme` (from TODO 54) replaces `ThemeRegistry.lookup(diagram.theme_id)`
+4. ColorResolver and FontResolver accept `Definition` directly
+5. Keep backward-compat aliases in EaEmitter (deprecated)
+
+## Acceptance
+
+- EaEmitter references Ea::Theme::*
+- diagram.theme used everywhere (replacing manual Registry lookup)
+- All existing specs pass

data/TODO.fixup/56-theme-yaml-files.md

@@ -0,0 +1,65 @@
+# 56 - Theme Definition YAML Files
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Theme definitions should be in human-editable YAML files (like
+`stereotype_colors.yml`), not hard-coded Ruby constants.
+
+## What needs to change
+
+1. `config/themes/default.yml` — no theme override
+2. `config/themes/119.yml` — EA White Theme (Carlito 7pt)
+3. Both follow the YAML format defined in TODO 53
+4. Ea::Theme::Loader auto-loads from config/themes/ on first
+   Registry access
+
+## default.yml
+
+```yaml
+id: default
+name: Default (element-stored values)
+font:
+  family: null
+  size: null
+  unit: px
+text:
+  color: "#000000"
+  weight_normal: 400
+  weight_bold: 700
+border:
+  color: "#000000"
+  stroke_width: 2
+fills: {}
+```
+
+## 119.yml
+
+```yaml
+id: "119"
+name: EA White Theme
+font:
+  family: Carlito
+  size: 7
+  unit: pt
+text:
+  color: "#595959"
+  weight_normal: 0
+  weight_bold: 700
+border:
+  color: "#9A8484"
+  stroke_width: 1
+fills:
+  Ea::Model::Klass: "#FDFAF7"
+  Ea::Model::Interface: "#F1ECFA"
+  Ea::Model::DataType: "#FAF9E6"
+  Ea::Model::Enumeration: "#E8FDE3"
+  Ea::Model::PrimitiveType: "#FAF9E6"
+```
+
+## Acceptance
+
+- Both YAML files exist and parse correctly
+- Loader loads them into Registry
+- Registry.lookup("119") returns Definition with all fields

data/TODO.fixup/57-theme-specs-and-integration.md

@@ -0,0 +1,27 @@
+# 57 - Theme Specs and Integration Test
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+The Theme refactor (TODO 51-56) is a major architectural change.
+Comprehensive specs are needed to verify:
+1. YAML loading
+2. Definition immutability + #with
+3. Registry OCP (register new themes)
+4. Diagram#theme API (get/set/override)
+5. Integration: render with custom theme
+
+## What needs to change
+
+1. `spec/ea/theme/definition_spec.rb` — value object behavior
+2. `spec/ea/theme/registry_spec.rb` — registry + YAML loading
+3. `spec/ea/theme/loader_spec.rb` — YAML parsing
+4. `spec/ea/model/diagram_theme_spec.rb` — Diagram#theme API
+5. Integration spec: render with custom theme, verify output
+
+## Acceptance
+
+- All spec files created with comprehensive coverage
+- >90% line coverage on Ea::Theme::*
+- All existing specs pass

data/TODO.fixup/58-ea-entry-point-theme-autoload.md

@@ -0,0 +1,20 @@
+# 58 - EA::Ea.rb Entry Point Autoload for Theme
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+`Ea::Theme` is a new top-level namespace. It needs proper autoload
+registration in `lib/ea.rb` (the gem entry point).
+
+## What needs to change
+
+1. `lib/ea/theme.rb` — module entry file with autoloads
+2. `lib/ea.rb` adds `autoload :Theme, "ea/theme"`
+3. All Theme sub-files follow autoload pattern
+
+## Acceptance
+
+- `require "ea"` makes `Ea::Theme::*` available
+- No require_relative in any Theme file
+- All autoloads defined in `lib/ea/theme.rb`

data/TODO.fixup/59-thread-theme-through-all-renderers.md

@@ -0,0 +1,29 @@
+# 59 - Thread Theme Through All Renderers
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Only `Elements` consults `diagram.theme`. Four other renderers
+hardcode values:
+- `Labels` — hardcodes Yu Gothic UI 13px, #000000 fill
+- `DiagramFrame` — hardcodes Calibri 7pt, #000000 fill
+- `Connectors` — hardcodes stroke-width:2 via Style constant
+- `Markers` — hardcodes stroke-width:2 via Style constant
+
+Theme :119 needs sw=1, Carlito 7pt, #595959 text everywhere.
+
+## What needs to change
+
+1. `LayerSequencer` reads `diagram.theme` and passes to all
+   child renderers via constructor param.
+2. Labels gains `theme:` → uses theme.font_family / text_color
+3. DiagramFrame gains `theme:` → uses theme.font_family / text_color
+4. Connectors/Markers gain `theme:` → use theme.stroke_width
+
+## Acceptance
+
+- All renderers receive and use theme
+- Theme :119 diagrams render all text in #595959
+- All connector lines render at sw=1 when themed
+- Existing specs pass

data/TODO.fixup/60-cli-theme-option.md

@@ -0,0 +1,22 @@
+# 60 - CLI --theme Option for ea svg Command
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+The `ea svg NAME FILE` CLI command renders a diagram. Users
+cannot override the theme from the command line. Adding a
+`--theme=ID` flag lets users test different themes without
+modifying the QEA/XMI source.
+
+## What needs to change
+
+1. `Ea::Cli::Command::Svg` accepts `--theme=ID` option
+2. When provided, sets `diagram.theme = ID` before rendering
+3. `--theme=default` resets to no-theme
+4. `--theme=list` prints available theme IDs
+
+## Acceptance
+
+- `ea svg MyDiagram model.xmi --theme=119` works
+- `ea svg MyDiagram model.xmi --theme=list` lists themes

data/TODO.fixup/61-theme-validation.md

@@ -0,0 +1,28 @@
+# 61 - Theme Definition Validation
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+`Ea::Theme::Definition.new` accepts any values without
+validation. Invalid data (malformed hex, negative font_size,
+nil required fields) produces silently broken rendering.
+
+## What needs to change
+
+1. `Definition#initialize` validates:
+   - id is non-empty string
+   - colors match /^#[0-9A-Fa-f]{6}$/
+   - font_size is nil or positive integer
+   - stroke_width is positive integer
+   - text_weight_normal/bold are integers
+2. Raises `ArgumentError` with descriptive message on violation
+3. Skip validation when loading from YAML (trust source) — use
+   `Definition.new(..., validate: false)` or `Definition.from_hash`
+
+## Acceptance
+
+- Invalid hex raises ArgumentError
+- Negative font_size raises ArgumentError
+- Empty id raises ArgumentError
+- Valid Definition passes without error

data/TODO.fixup/62-theme-builder-dsl.md

@@ -0,0 +1,31 @@
+# 62 - Theme Builder DSL
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+Creating themes programmatically via `Definition.new(id:..., font_family:..., ...)`
+is verbose. A builder DSL provides a more ergonomic, intention-revealing API.
+
+## Proposed API
+
+```ruby
+Ea::Theme.build("my_theme", name: "My Theme") do |t|
+  t.font family: "Arial", size: 12, unit: "px"
+  t.text color: "#333333", weight_normal: 400
+  t.border color: "#666666", stroke_width: 1
+  t.fill "Ea::Model::Klass" => "#F0F0F0"
+end
+```
+
+## What needs to change
+
+1. `Ea::Theme.build(id, name: nil)` yields a builder
+2. Builder methods set attributes
+3. Returns a Definition registered in Registry
+
+## Acceptance
+
+- DSL creates valid Definition
+- Definition is registered for lookup
+- New spec covers DSL usage

data/TODO.fixup/63-theme-integration-rendering-spec.md

@@ -0,0 +1,24 @@
+# 63 - Theme Integration Rendering Spec
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+The theme system has unit specs but no end-to-end integration
+test verifying that a themed diagram renders with the correct
+font, colors, and stroke widths in the SVG output.
+
+## What needs to change
+
+1. Spec loads simple.qea/model.xml
+2. Sets diagram.theme = "119"
+3. Renders via Ea::Svg::EaEmitter::Document
+4. Parses SVG output and asserts:
+   - Text fill is #595959 (not #000000)
+   - Element stroke is #9A8484 (not #000000)
+   - Stroke-width is 1 (not 2)
+   - Font-family is Carlito (not Calibri)
+
+## Acceptance
+
+- Integration spec verifies all theme attributes in rendered SVG

data/TODO.fixup/64-theme-writeback-styleex.md

@@ -0,0 +1,21 @@
+# 64 - Theme Write-Back to StyleEx
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+When `diagram.theme = :119` is called, the theme_override_id is
+set in memory. There's no way to persist this back to the QEA's
+`t_diagram.StyleEx` field.
+
+## What needs to change
+
+1. `Diagram#to_style_ex` — serializes style_ex_flags back to
+   `Key=Value;` format, merging theme_id into existing flags
+2. QEA writer (when implemented) uses this to write back
+3. Diagram#apply_theme_to_style_ex — mutates style_ex in-place
+
+## Acceptance
+
+- Diagram.to_style_ex produces valid StyleEx string
+- Theme ID round-trips through to_style_ex → from_style_ex

data/TODO.fixup/65-remove-dead-eaemitter-theme-files.md

@@ -0,0 +1,30 @@
+# 65 - Remove Dead EaEmitter Theme Files
+
+## Status: DONE (2026-07-26)
+
+## Context
+
+After promoting Theme to Ea::Theme::*, the old files remain:
+- `lib/ea/svg/ea_emitter/theme.rb`
+- `lib/ea/svg/ea_emitter/theme_registry.rb`
+- `lib/ea/svg/ea_emitter/theme_colors.rb`
+
+These are no longer loaded (autoloads removed, replaced with
+constant aliases). They're dead code sitting on disk.
+
+## What needs to change
+
+The EaEmitter module file now uses aliases:
+```ruby
+Theme = ::Ea::Theme::Definition
+ThemeRegistry = ::Ea::Theme::Registry
+```
+
+The old physical files should be marked as deprecated or removed.
+Per the user's "NEVER DELETE FILES" rule, mark as deprecated with
+a pointer to the new location, don't delete.
+
+## Acceptance
+
+- Old files have deprecation notice
+- No code loads them