0022. A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract¶
In short
A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract, loaded at runtime. Status: Accepted (2026-11-08).
Status: Accepted (2026-11-08)
Context¶
The portal (spec 0008, #729) is a PWA with no build and no framework: static/index.html, app.js and app.css, served by the nereus-portal Nereid on port 8081. It forwards /v1/* to the Nereus API (ADR 0018, the one door) and sends a Content Security Policy of default-src 'self', connect-src 'self' <issuer origin> and frame-ancestors 'none'. Reefs and their Nereids extend the CLI with their own commands (ADR 0004), and reefs are installed at runtime (ADR 0010); the portal has no such extension point, and #46 asks that "a new Controller adds screens without a portal release".
The owner asked on 2026-11-06 "microfrontends? Module? How?" (#1102, Tide in the portal; this is its step 1, #1103). Tide, the idea timeline, is the first screen that belongs to a reef that is not the portal: the ideas reef. The tabs already planned as portal features (#740 status, #750 orders, #777 threads) show the platform's own state, not a reef's.
The Nereid's contract today is GET / on its controller port (8080, inside the cluster only), an object such as {"name": "nereus-portal", "commands": []}. Errors follow ADR 0012: what happened, the cause, how to check, how to fix, in one line per field.
Decision¶
A reef adds a screen to the portal as a Web Component its Nereid serves. The options weighed:
| Option | What it is | Fits | Against |
|---|---|---|---|
| Module of the portal | One more tab in controllers/nereus-portal/static/ |
The fastest first slice | Every capability needs a portal release; the portal grows to know every reef, the opposite of ADR 0004, ADR 0010 and #46 |
| Microfrontend at runtime, Web Components | The reef's Nereid serves an ES module that defines a custom element; its contract names it; the portal loads it when the reef is installed | Mirrors ADR 0004 for the portal; no build and no framework, like the portal; same origin, so the CSP stays 'self' |
A small contract to design and keep stable |
| Module Federation | Webpack or Rspack federated bundles | Mature for big SPA teams | Needs a build and a shared runtime; the portal has neither |
| single-spa | A root config that mounts apps | Framework-agnostic | A second router and lifecycle on top of a 200-line app |
| iframe | The Nereid serves a whole page, framed | Strong isolation | Breaks the PWA's theme, language and sign-in; frame-ancestors 'none' today |
| Backstage plugin | The wasp-idp path (#30) |
Ecosystem | A Backstage instance the portal does not have |
The contract gains a screens list, versioned by a contractVersion field (an integer, 1 with this ADR; a Nereid with no contractVersion serves no screen). Each entry has exactly these fields; an unknown field makes the entry ignored, never half-loaded:
{
"name": "doris",
"commands": [],
"contractVersion": 1,
"screens": [
{"tab": "Tide", "element": "nereus-tide", "module": "tide.js", "icon": "waves"}
],
"assets": ["tide.css"],
"uiPort": 8082
}
tab: the label of the tab.element: the custom element's tag name, which must start withnereus-and contain a hyphen.module: a file name of the Nereid'sui/folder, no slash and no dot segment, ending in.js.icon: the name of an icon the portal already has, else a default.- The portal's Nereid reads the screens from each Nereid's
status.screens(the SDK copies the contract's list there, so the cluster holds one list and the API reads what Nereids publish, ADR 0018), and the portal asks the API for them (GET /v1/screens, built in #1105). A tab shows only while its reef is installed.
The portal's Nereid forwards /reefs/<reef>/ui/<file>, not the API (the open point of #1103, decided as recommended). The forward serves static files only, from an allow-list built from the contracts: GET only, a file that some screens entry names (module) or that sits in the Nereid's ui/ folder and is listed by the same contract in assets (an optional list of file names, such as a stylesheet or an icon), no query, no dot segment, backslash or percent-encoded slash (the check /v1 already has). It forwards to the reef's Nereid on its controller port, GET /ui/<file>, which answers only files it listed in the contract; anything else is 404. A Nereid may serve ui/ on a port of its own instead, named by the contract's optional uiPort (an integer from 1024 to 65535, copied to its status like screens; #1108), so a NetworkPolicy opens that port to the portal's pods without opening the Nereid's data, since it holds a port, not a path; the forward then targets that port. Same origin, so the CSP stays 'self' and no header is relaxed. The API does not carry code: it carries data.
The element's interface. The portal creates the element with document.createElement(element) after import("/reefs/<reef>/ui/<module>") and sets, as properties and never as globals:
api: an object withget(path),post(path, body)anddelete(path), each afetchbound to/v1with the person's token; the token itself is never given. A path outside/v1is refused.lang:pt-BRoren, set again when the person switches the language.- The theme as CSS custom properties the portal defines on
:root(--nereus-bg,--nereus-fg,--nereus-muted,--nereus-accent,--nereus-border,--nereus-radius,--nereus-font), which cross the shadow boundary; the palette followsprefers-color-schemeas the portal's does. - The element owns its shadow DOM (mode
open) and its styles; the portal's CSS does not reach it. - The element reads and writes data only through
/v1(ADR 0018), never from the screen to the Nereid directly:connect-srchas no other origin, so the browser enforces it. - It dispatches
nereus-error(aCustomEventwhosedetailhas the ADR 0012 fieldsmessage,cause,checkandfix) when it cannot work, and the portal shows that line in the tab. It sets no title, route or history of its own. - It may dispatch
nereus-focus(aCustomEventwhosedetail.focusedistrueorfalse) when it shows one item and when it goes back to its list (#1761): while focused, the portal hides its mark, its language switch and its tab bar, and the screen takes the whole view, as a phone app hides its tabs inside a detail. - It may dispatch
nereus-signin(aCustomEventwhosedetail.resumeis a small JSON value, at most 1 KB) when a call still answers 401 after the portal's renewal, the sign-in having ended (#1910): the portal signs in again by a full redirect and, back, opens that screen at once and sets itsresumeproperty to that value beforeapi, so the screen reopens where it was.
When a module fails to load (a 404, a syntax error, a customElements.define that throws, the element never defined within 10 seconds, or a nereus-error), the tab shows the error line of ADR 0012, with the reef and the file named, and the rest of the portal keeps working. The portal never retries on its own; the person reloads the tab.
The portal's built-in tabs (#740, #750, #777) stay modules of the portal: they are the platform's own, not a reef's, and need no contract.
Tide is the first consumer: the ideas reef's Nereid doris serves tide.js, which defines <nereus-tide>, and reads its notes from GET /v1/ideas/notes (#1107). It proves the extension point against a real screen, not an abstract one.
Prior art¶
- Custom Elements and Shadow DOM (WHATWG HTML Standard, custom elements): the browser's own component model, with no library; the contract is one tag name and one module.
- Backstage's frontend plugins (backstage.io): the portal loads a plugin's UI at runtime; Nereus keeps the idea and drops the build and the framework.
- Module Federation (module-federation.io) and single-spa (single-spa.js.org): the microfrontend patterns weighed above; the pattern is the same (an independent team ships a screen), the mechanism here is the platform's.
- Micro Frontends (micro-frontends.org, Cam Jackson on martinfowler.com): the case for Web Components as the integration contract between a shell and its parts.
Consequences¶
- The same contract carries a reef's MCP tools (ADR 0029, a
toolslist read withcontractVersion2), served by the Nereus API at/mcp. - A reef adds a screen with no portal release: install the reef and its Nereid, and the tab appears.
- The Nereid SDK and
templates/nereidlearn thescreens,assetsandcontractVersionfields and serveui/(#1105 builds the portal's side and the SDK's). - The portal's Nereid gains a read of the Nereids' status and a forward to another Nereid's controller port; its admission policy and Role change in the same issue. A
screensentry cannot make the portal fetch anything outside the allow-list. - A reef's screen runs code in the portal's origin, with the person's token reachable through
api. Installing a reef is therefore trusting its code as the portal's own (OWASP A08); the allow-list and the'self'CSP limit where it can reach, not what it does with the data it may read. A signed module is a later decision. - The contract is versioned: a change that breaks an element's interface raises
contractVersion, and the portal loads only the versions it knows, with the ADR 0012 line for the others. - Until v1.0.0 this ADR is rewritten in place when the decision changes (ADR 0001).
Origin¶
Decided as a recommendation on 2026-11-06 and 2026-11-08 in #1102 and #1103, from the owner's question about microfrontends; raw data in #pontos/raw/2026-11-06/ (Drive) for the voice session of that day.
Open questions¶
- Signing the modules a Nereid serves, so the portal loads only code a Mandate approved.
- Whether a screen may offer a command to the CLI as well, as ADR 0004 does for commands.
- Isolating a reef's screen from the portal's origin (a sandboxed iframe or an origin of its own, with a narrow API over
postMessage), so its code cannot reach the person's token; until then the portal keeps the browser's ownfetchbefore any reef module loads, and its forward follows no redirect and sets each file's type from its extension (#1105).