ADR-0015 — Modular UI chrome and embed modes
Enable zero-FOUC minimal chrome, inspector toggling, and kiosk display modes via URL query parameters, hash fragments, and declarative CSS.
Status: accepted
Compiled standalone HTML diagrams previously rendered desktop application chrome including topbar breadcrumbs, search docks, and sidebar slideouts. Marrow now supports zero-FOUC embed and kiosk modes through URL query parameters (?chrome=minimal, ?inspector=off, ?minimap=off, ?theme=light) and hash fragments (#embed=true).
Why
Embedding full diagram chrome into dashboards, documentation wikis, or monitoring displays caused visual clutter and wasted screen real estate.
Generating separate embed-specific HTML targets during the build was considered and rejected. Compiling distinct files per topology doubled build artifacts, complicated CI pipelines, and increased storage overhead.
Hiding UI chrome via client-side JavaScript after window.onload was also rejected. Post-mount DOM mutation causes visible flashes of unstyled content (FOUC) and jarring layout shifts.
To eliminate FOUC, a pre-boot script in the document <head> parses query and hash parameters synchronously before first paint. The script applies state attributes (data-chrome="minimal", data-inspector="off", data-minimap="off") directly to document.documentElement. Declarative CSS selectors (html[data-chrome="minimal"] .m-breadcrumbs, html[data-chrome="minimal"] .m-dock { display: none; }) suppress extraneous controls instantly before content renders.
In addition, @marrow/runtime listens for hashchange events. Host pages embedding diagrams inside <iframe> containers can toggle chrome or theme states dynamically without reloading the iframe document.
Consequences
Single versatile artifact. One generated HTML file serves as an interactive desktop tool, an embedded dashboard widget, or a clean kiosk display.
Zero visual flash. Declarative <head> attribute initialization prevents flashes of unstyled content and layout shifts during page load.
Retained interactivity. Minimal chrome hides navigation rails and breadcrumbs while keeping zoom, pan gestures, device selection, and tooltips fully interactive.
Considered and rejected
Separate embed build artifacts. Rejected because maintaining multiple build flavors doubled compilation times and asset storage requirements.
Asynchronous postMessage negotiation. Rejected because asynchronous handshake messages cannot prevent the initial frame from painting full chrome before hiding it.