Skip to content

ADR-016: Portal-Component RFC #182 Conformance + Embeddable Panes

Date: 2026-06-21 Status: Accepted Decision-makers: FCC core maintainers Consulted: AOME RFC #182 portal-component-v1 contract (co-owners CTO/AURORA/PAOM/RC); PHOENIX/CONSTEL live descriptors Informed: AOME / AURORA portal hosts — coordination via GitHub notice (Channel-B)

Context and Problem Statement

FCC began serving /.well-known/portal-components.json in v1.10.0 (Phase 2), but the manifest was non-conformant to the AOME RFC #182 contract (aome_ext/src/aome/federation/component_registry.py::_ALLOWED_COMPONENT_KEYS): it used profile (not spec), name/route/mount/url (not the allowed keys), and its components pointed at SPA routes rather than embeddable panes. A host validating against _ALLOWED_COMPONENT_KEYS (strict — unknown keys rejected) would reject every FCC component, and even if accepted there was nothing renderable to mount.

Decision

  1. Conform the manifest to RFC #182 (protocols/portal.py): top-level spec: "portal-component-v1"; each component carries only the 12 allowed keys — id (lowercase dotted), title, publisher, render_mode (iframe), iframe_url, persona_scope (subset of the RT-49 personas consumer/privacy-expert/scientist/auditor/admin), theme (tokens-v1), refresh_interval_s, enabled. A validate_component() helper mirrors the host's allowed-keys/persona-scope/id/render-mode checks so a test asserts zero conformance problems (the 12/12 bar PHOENIX hit).
  2. Serve real embeddable panes at /embed/<slug> from the UX gateway — server-rendered, CORS-free, JS-light HTML (no SPA, no external scripts) for personas, ecosystem, and compliance, so a host iframe actually renders FCC content offline.
  3. tokens-v1 theme: panes ship a minimal CSS-variable contract (--fcc-bg/-fg/-accent/-muted/-border) a host can override; defaults keep the pane legible standalone.
  4. Mount remains host-pull (Channel-B): FCC publishes the well-known doc + serves the panes; the host ingests. FCC issues a coordination notice to AOME/AURORA and never edits their repos.

Consequences

  • FCC components are now mountable by an RFC-#182 host with zero rejected keys.
  • The panes are deliberately minimal/server-rendered (not the rich React SPA) — this is the universal, host-knowledge-free path; richer native rendering can follow if a host adopts a shared kit.
  • Coordination with AOME/AURORA is a notice, not a code change on their side until they choose to ingest.
  • The old PORTAL_COMPONENT_PROFILE/name/route/mount surface is replaced; the v1.10.0 manifest consumers (none external yet — greenfield) move to the conformant shape.