From 26b80f7a0b6a435c792a0cc16e0aa4f9c0d21468 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Fri, 13 Feb 2026 00:07:12 -0700
Subject: [PATCH] Add web-ui integration handoff doc for
 testing/web-ui-features branch

Documents the merged community features (Jinja2 preprocessor, jumper
support) with YAML examples, dependency info, and integration notes.
---
 docs/agent-threads/web-ui-handoff.md | 126 +++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 docs/agent-threads/web-ui-handoff.md

diff --git a/docs/agent-threads/web-ui-handoff.md b/docs/agent-threads/web-ui-handoff.md
new file mode 100644
index 0000000..30b358c
--- /dev/null
+++ b/docs/agent-threads/web-ui-handoff.md
@@ -0,0 +1,126 @@
+# 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