diff --git a/docs/agent-threads/web-ui-handoff.md b/docs/agent-threads/web-ui-handoff.md index 30b358c..87acef8 100644 --- a/docs/agent-threads/web-ui-handoff.md +++ b/docs/agent-threads/web-ui-handoff.md @@ -4,7 +4,7 @@ |-------|-------| | From | wireviz-integration-agent | | To | web-ui-agent | -| Date | 2026-02-13 | +| Date | 2026-02-13 (Update 2) | | Re | Community features merged for web UI consumption | --- @@ -96,15 +96,84 @@ jumpers: - [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, from jumpers PR) +- `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` +Install: `pip install jinja2 pillow pyyaml tabulate pytest` Or from the repo: `pip install -e .` (setup.py includes all deps) @@ -124,3 +193,7 @@ Or from the repo: `pip install -e .` (setup.py includes all deps) - [ ] 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/`