ADR-0018 — Diagram-level documentation modal and watermarked attribution
Add declarative about metadata schema, interactive document modal dialog, and permanent Marrow watermarked attribution.
Status: accepted
Marrow topologies previously lacked a first-class mechanism for attaching diagram-level architectural context, maintenance window runbooks, or operational contacts. The viewer's menubar action "About this diagram" merely opened the left navigation sidebar, which displayed only compiler layout metrics. Marrow now provides a declarative about: schema, an interactive CAD blueprint document dialog modal (.m-about-dialog), and permanent Marrow watermarked attribution.
Why
Enterprise diagrams serve dual purposes: visual topology mapping and operational documentation. Engineers reviewing complex topologies require immediate access to architecture decisions, design constraints, and emergency escalation contacts without navigating to external wikis or tracking separate design documents.
Directing users to the left sidebar was considered and rejected. The sidebar has a fixed width (260 px) optimized for page navigation hierarchies, making it unsuitable for multi-column tables, change notes, or technical specifications.
Opening a separate about.html web page was also rejected. Marrow diagrams are distributed as self-contained offline HTML artifacts (--single). Relying on a separate HTML file breaks offline portability and fails when diagrams are embedded as inline components.
The runtime now features an in-diagram document modal dialog (.m-about-dialog) built with backdrop blur, quick metadata status pills (Author, Revision, Date, Devices, Links, Zones), and support for both freeform Markdown and structured section dictionaries. An oversized, low-opacity Marrow arrowhead watermark is embedded into the modal background, and the footer stamps an authentic "Engineered with Marrow" credit badge linking to the project repository.
Consequences
Self-contained operational documentation. Topology authors can document architectures, maintenance procedures, and support contacts directly inside the YAML topology file.
Offline portability preserved. The document dialog operates entirely client-side with zero external assets, preserving single-file offline distribution.
Durable attribution credit. The Marrow watermark and footer credit badge ensure the compiler and project receive credit across all shared, published, and exported diagrams.
Programmatic accessibility. Host applications embedding Marrow diagrams can trigger the documentation view using the JavaScript client API via window.marrow.openAbout().
Considered and rejected
Dedicated external about.html route. Rejected because single-file diagrams must remain completely self-contained without multi-file dependencies.
Reusing the navigation sidebar. Rejected because the 260 px sidebar drawer lacks sufficient horizontal width to format Markdown tables or operational runbooks cleanly.