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 (Update 2)
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

Update 2 — Additional Ports & Hardening (2026-02-13)

The following features were ported from upstream PRs and landed on testing/web-ui-features after the initial handoff.

3. PDF Output (port of upstream PR #367)

PDF is now a supported output format via GraphViz native rendering.

What changed:

• New CLI flag: -f P generates PDF alongside other outputs
• P added to the allowed format list in wv_harness.py and wv_cli.py
• GraphViz renders the PDF natively (no intermediate conversion step)

Web UI implications:

• Offer a "Download PDF" option alongside SVG/PNG
• PDF output is vector-based, so it scales well for printing wiring diagrams

4. Strip Length Specs (port of upstream PR #446)

Connectors now support a strip property specifying sleeve and insulation removal lengths. Useful for documenting wire prep instructions alongside the harness diagram.

What changed:

• New dataclasses: StripSpec and Strip in wv_dataclasses.py
• Strip info rendered in connector diagram nodes via wv_graphviz.py
• New strip: key under connector definitions in YAML

Example:

connectors:
  X1:
    type: Molex KK
    pincount: 4
    strip:
      sleeve: "25 mm"
      insulation: "5 mm"

Web UI implications:

• Connector detail views / forms should expose strip length fields
• Values are strings (include units), so a simple text input works
• Strip info appears in the rendered diagram, no special rendering needed in the UI

5. YAML-in-PNG Round-Trip (port of upstream PR #234, hardened)

PNGs now embed the original YAML source as compressed iTXT metadata. This allows round-tripping: export a PNG, then later extract the full harness definition back out.

What changed:

• New module: wv_png_metadata.py with key functions:
  • save_yaml_to_png(yaml_str, png_path) — embed YAML into an existing PNG
  • read_yaml_from_png(png_path) — extract YAML from a PNG
  • has_yaml_metadata(png_path) — check if a PNG contains embedded YAML
• Uses atomic writes (temp file + rename) to avoid corrupting PNGs on failure
• Preserves existing PNG metadata (doesn't clobber other iTXT chunks)
• 10 MB size guard when reading untrusted PNGs
• Version tag: wireviz_meta_version: "1" for future compatibility
• 19-test suite in tests/test_png_metadata.py

Web UI implications:

• Users can drag-and-drop a WireViz PNG to import a harness definition
• Use has_yaml_metadata() to detect whether a PNG is a WireViz export
• Sharing harness designs becomes trivial — the PNG is the source file
• The 10 MB guard protects the server from oversized uploads

6. Code Quality Improvements

• ParsedInput NamedTuple in wireviz.py for clean data flow between parsing stages
• output_formats normalized to a tuple internally, preventing substring matching bugs (e.g., "P" in "PNG" no longer incorrectly matches)

Dependencies

The merged branch requires these Python packages beyond upstream:

• jinja2 (for template preprocessor)
• pillow (for image handling, PNG metadata, from jumpers PR)
• pyyaml (explicit dep, from jumpers PR)
• tabulate (for BOM formatting, from jumpers PR)
• pytest (for running the test suite)

Install: pip install jinja2 pillow pyyaml tabulate pytest

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
• Expose PDF output option in web UI
• Display strip length info in connector detail views
• Leverage YAML-in-PNG for sharing/importing harness diagrams from PNGs
• Run test suite: .venv/bin/pytest tests/