Entry point for rendering A2UI surfaces as Phoenix function components.

Dispatches each component type to its module via a compile-time type registry built from default components and application config.

Compile-time configuration

The type registry is assembled at compile time from two config keys:

• :component_modules — a %{String.t() => module()} map of custom or override component modules. Default: %{}.
• :use_default_components — when true (the default), the 18 built-in components are included and your custom modules are merged on top. Set to false to supply your own complete set.

Override a built-in component

# config/config.exs
config :a2ui, component_modules: %{
  "Button" => MyApp.A2UI.Button
}

Add a new component type

config :a2ui, component_modules: %{
  "StatusBadge" => MyApp.A2UI.StatusBadge
}

Replace all defaults

config :a2ui,
  use_default_components: false,
  component_modules: %{
    "Text" => MyApp.A2UI.Text,
    "Button" => MyApp.A2UI.Button
    # ... only your modules are used
  }

Use default_components/0 to inspect the built-in type → module map at runtime (e.g. to merge programmatically in a test).

Theme CSS variables

When a createSurface message includes a theme map, the renderer applies matching values as CSS custom properties on the .a2ui-surface wrapper div. This lets agent-provided theme colors cascade to all child components via standard CSS inheritance.

Currently supported mappings:

The built-in CSS references --a2ui-primary for buttons, focus rings, and other accent elements with a fallback default in :root. A per-surface theme override takes precedence without affecting other surfaces on the page.

Properties with nil values are omitted from the inline style.

Writing custom components

See A2UI.ComponentRenderer for the behaviour, assigns contract, available helpers, and a full example.