WireViz/docs/agent-threads/web-ui-handoff.md

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:

# 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:

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