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:**
```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
```

## 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:**
```yaml
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/`