# WireViz Fork — Web UI Integration Guide

| Field | Value |
|-------|-------|
| From | wireviz-integration-agent |
| To | web-ui-agent |
| Date | 2026-02-13 |
| Re | Community features merged for web UI consumption |

---

## Repository

- **Gitea**: https://git.supported.systems/warehack.ing/WireViz
- **Upstream**: https://github.com/wireviz/WireViz
- **Testing branch**: `testing/web-ui-features`

## Branch Layout

```
master                        ← upstream mirror (v0.4.1)
feature/jinja2-preprocessor   ← PR #382 (standalone)
feature/jumpers               ← PR #455 (standalone)
testing/web-ui-features       ← combined: jinja2 + jumpers merged together
```

The web UI should target `testing/web-ui-features` as its WireViz dependency.

## Merged Features

### 1. Jinja2 Preprocessor (upstream PR #382)

YAML harness definitions now pass through a Jinja2 templating stage before parsing. This enables:

- **`{% include %}`** — compose harnesses from reusable connector/cable definition files
- **`{% for %}`** — generate repetitive pin/wire definitions with loops
- **`{% if %}`** — conditional sections (e.g., optional debug connectors)
- **Template variables** — parameterize harness definitions

**CLI additions:**
- `-I / --include-path` — specify search path for Jinja2 `{% include %}` templates
- Outputs a `.rendered.yml` alongside other outputs showing the expanded YAML

**Web UI implications:**
- Users can define reusable connector/cable "libraries" as partial YAML files
- The web UI could offer a template variable input form
- `.rendered.yml` is useful for debugging — consider showing it in a "debug" panel
- The Jinja2 `Environment` uses `FileSystemLoader`, so template includes are path-relative

**Example:**
```yaml
# connectors.yml (reusable library)
connectors:
  DB9M:
    type: D-Sub
    subtype: male
    pincount: 9

# main_harness.yml
{% include 'connectors.yml' %}
cables:
  W1:
    wirecount: 4
    colors: [BK, RD, GN, BU]
```

### 2. Jumper Wire Support (upstream PR #455)

Major refactor adding jumpers as a first-class component alongside connectors and cables. This is a significant internal rewrite:

**What changed:**
- New `jumpers:` top-level YAML section for defining jumper wires
- Module renames: `DataClasses.py` -> `wv_dataclasses.py`, `Harness.py` -> `wv_harness.py`
- New color system: `SingleColor` / `MultiColor` dataclasses replacing string-based colors
- New BOM system: `BomEntry` / `BomHash` namedtuples for cleaner bill-of-materials
- New examples: `ex15` and `ex16` demonstrate jumper usage
- Version bumped to `0.5-dev+refactor`

**Web UI implications:**
- The YAML schema now has a `jumpers:` section — UI forms/editors need to support this
- BOM output format may differ from upstream v0.4.x — verify your BOM parser
- Color handling is now richer (multi-color wires) — UI color pickers could leverage this
- Example files in `examples/` are all regenerated — good test fixtures

**Example:**
```yaml
connectors:
  J1:
    type: Header
    pincount: 4
jumpers:
  JP1:
    from: J1
    to: J1
    connections:
      - [1, 2]  # jumper between pins 1 and 2
```

## Dependencies

The merged branch requires these Python packages beyond upstream:
- `jinja2` (for template preprocessor)
- `pillow` (for image handling, from jumpers PR)
- `pyyaml` (explicit dep, from jumpers PR)
- `tabulate` (for BOM formatting, from jumpers PR)

Install: `pip install jinja2 pillow pyyaml tabulate`

Or from the repo: `pip install -e .` (setup.py includes all deps)

## Known Considerations

1. **Jinja2 + Jumpers interaction**: Not explicitly tested together yet. The Jinja2 stage runs first (text preprocessing), then YAML parsing handles jumpers. Should work fine since they operate at different layers, but worth verifying with a combined test case.

2. **Version string**: Shows `0.5-dev+refactor` — the web UI should not rely on version parsing against upstream releases.

3. **Generated outputs**: All example SVG/PNG/HTML files in `examples/` and `tutorial/` are from the jumpers PR. The Jinja2 examples are in `examples/jinja/`.

---

**Next steps for recipient:**
- [ ] Point web UI's WireViz dependency at `git+https://git.supported.systems/warehack.ing/WireViz@testing/web-ui-features`
- [ ] Update YAML schema/editor to support `jumpers:` section
- [ ] Add Jinja2 template support in the UI (include path, template variables)
- [ ] Test BOM output parsing against the new format
- [ ] Create a combined test case using both Jinja2 templates and jumper definitions