ADR-0017 — Configurable blueprint export chrome
Add modular engineering title blocks, dynamic auto-legends, and forced port label visibility to static SVG and PNG exports.
Status: accepted
Static SVG and PNG diagram exports previously captured raw viewport geometry without a legend, title block, or visible interface ports. Marrow now provides a modular export pipeline that automatically stamps an engineering title block, generates an active topology legend, and forces interface port labels to remain visible on static exports.
Why
Static diagram exports are primary artifacts for architectural reviews, change management records, audit binders, and compliance documentation. The live viewer hides interface port labels at higher zoom levels to prevent visual clutter, but static exports require complete endpoint clarity without manual zooming.
Capturing the raw live viewport was considered and rejected. Viewport captures omit diagram metadata (diagram title, author, date, revision, organization mark) and omit explanations of link styles (such as double-rail trunks, dashed tunnels, and status colors), forcing engineers to manually annotate exports in external drawing tools.
Generating static legends that list every link type supported by Marrow was also rejected. A universal legend lists unused link modes and clutter diagrams with irrelevant keys.
The export pipeline now analyzes the active topology and dynamically expands the canvas with a blueprint footer. An engineering title block displays title, author, date, revision, and logo declared in topology YAML or inherited from configuration. An auto-legend module scans links on the active page, identifies unique modes, speeds, and mediums in use, and generates matching vector swatches. Port labels (.m-portlabel) are forced visible during rasterization and vector export.
Consequences
Production-ready engineering blueprints. Exported SVGs and PNGs function as self-contained engineering drawings suitable for audits, design documentation, and runbooks.
Context-aware auto-legend. The legend contains only the link modes and mediums present on the active diagram, preventing clutter from unused link categories.
Unconditional port readability. All interface port chips remain visible and sharp on static exports regardless of the camera zoom level in the interactive session.
Modular parameter control. Users can disable or customize the title block, legend, and port force-show behavior using query parameters (?export_title=off, ?export_legend=off, ?export_ports=off).
Considered and rejected
Universal static legend table. Rejected because listing unused link types (e.g. stack links on an unstacked WAN diagram) clutters the export.
Relying on external image editing tools. Rejected because requiring post-export manual cropping and title stamping defeats agentic automation.