webui

Overview ¶

Package webui serves deploy's local-first operator interface and is the seam where an embedding product supplies its own branding.

The package owns presentation only: the embedded templates and assets, the page and asset handlers, and the read-only snapshot endpoint. Agent execution, approvals, event publication, and fleet state belong to the containing core, which supplies them through ISnapshotProvider — the single input this package takes — and which mounts its own action endpoints and event stream alongside this handler.

Presentation is the package's one configurable policy, and it is configured in three widening steps. WithBrand replaces the product name, the agent name, the wordmark, and the design tokens; every other string in the UI stays literal. WithNavItem appends entries to the sidebar. WithUIOverlay resolves templates and assets against a caller-supplied filesystem before the embedded one. The palette is delivered as a served same-origin stylesheet rather than an inline style block, so the page's Content-Security-Policy stays 'self' for both styles and scripts no matter how far a caller goes.

Template override points ¶

An overlay template file contributes {{define}} blocks into the same namespace the embedded files use, so redefining one of the names below replaces exactly that much of the UI. These are the supported names, the whole of them, and the data each one receives:

"index.html"     the operator home page; receives the page data below
"chat.html"      the live session page; receives the page data below
"primaryNav"     the sidebar navigation list; receives the bound
                 navigation items, each carrying the NavItem fields
                 (Label, Href, Glyph, View) plus Active, Count, and
                 CountAttribute
"statusPill"     one status chip; receives the status string
"browserRoutes"  the body's data-route-* attributes; receives the route
                 table the browser client reads its URLs from
"browserEnums"   the body's data-enum-* attributes; receives the enum
                 table the browser client compares against

The two page blocks receive .Brand, .Snapshot, .Nav, .Routes, .Enums, .InitialJSON, .Unavailable, and .ChatSessionID. Every template helper the shipped blocks use is available to an override of them.

Two of these names are load-bearing beyond their markup. "browserRoutes" and "browserEnums" are how the browser client learns its URLs and enum spellings; an override that drops an attribute silently disables the behavior behind it. The embedded client also reads the navigation back out of the rendered DOM, so an overridden "primaryNav" keeps in-page view switching as long as its entries carry data-nav values naming sections the page rendered.

Worked examples ¶

Two runnable programs in this module compose these options through the composition root, at both ends of the range:

examples/custom-ui-page   the stock identity, one sidebar entry, and the
                          page behind it — the smallest useful extension
examples/custom-brand     a full rebrand: both brand-bearing names, a
                          wordmark drawn around a glyph its overlay adds, a
                          replaced palette, one sidebar entry, and its page

Each carries a hermetic suite that renders the pages without the infrastructure an assembled Core opens.

Callers may rely on New failing rather than returning a handler without a snapshot source, on Handler being safe for concurrent use once New returns, on MarshalSnapshot producing the one canonical JSON encoding the embedded browser client parses, on every URL the rendered pages emit coming from browserroutes rather than a literal in a template, on the asset URL space and its cache headers being the same for overlay and embedded files alike, and on an unconfigured handler rendering exactly the stock deploy identity.