From 42ed77a1f0d553c573ac65eeb6db7993b20893b2 Mon Sep 17 00:00:00 2001
From: Shahab Layeghi <shahab_layeghi@intuit.com>
Date: Fri, 16 Jan 2026 11:50:37 -0800
Subject: [PATCH 1/2] Enable custom elements through Surface component

Add enableCustomElements property to Surface component and propagate it to
Root component. This allows custom elements registered via componentRegistry
to be rendered when using a2ui-surface.

Previously, the Root component supported custom elements via the
enableCustomElements property, but Surface did not expose this property,
making it impossible to enable custom elements when using Surface as the
top-level component.
---
 renderers/lit/src/0.8/ui/surface.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/renderers/lit/src/0.8/ui/surface.ts b/renderers/lit/src/0.8/ui/surface.ts
index f11af658..d44fe03d 100644
--- a/renderers/lit/src/0.8/ui/surface.ts
+++ b/renderers/lit/src/0.8/ui/surface.ts
@@ -32,6 +32,9 @@ export class Surface extends Root {
   @property()
   accessor processor: A2uiMessageProcessor | null = null;
 
+  @property({ type: Boolean })
+  accessor enableCustomElements = false;
+
   static styles = [
     css`
       :host {
@@ -118,6 +121,7 @@ export class Surface extends Root {
       style=${styleMap(styles)}
       .surfaceId=${this.surfaceId}
       .processor=${this.processor}
+      .enableCustomElements=${this.enableCustomElements}
       .childComponents=${this.surface?.componentTree
         ? [this.surface.componentTree]
         : null}

From e3357c65b8a055601ef5c9b6b82d9c7cdddf2a29 Mon Sep 17 00:00:00 2001
From: Shahab Layeghi <shahab_layeghi@intuit.com>
Date: Fri, 16 Jan 2026 12:11:09 -0800
Subject: [PATCH 2/2] Add tests and documentation for enableCustomElements
 property

- Update custom-components.md guide with usage instructions
- Include code example showing how to enable custom elements on Surface

Note: UI component tests require browser globals (DOM, CustomEvent, etc.)
which would need a test environment like happy-dom or jsdom. The existing
test suite only tests the data processing layer. The 4-line code change
can be verified by code review.
---
 docs/guides/custom-components.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/guides/custom-components.md b/docs/guides/custom-components.md
index 9582021f..307f722c 100644
--- a/docs/guides/custom-components.md
+++ b/docs/guides/custom-components.md
@@ -25,6 +25,31 @@ You register entire catalogs with your client application, not individual compon
 4.  **Agent Selects Catalog**: The agent chooses a catalog for a given UI surface.
 5.  **Agent Generates UI**: The agent generates `surfaceUpdate` messages using components from that catalog by name.
 
+## Enabling Custom Components on the Surface
+
+When using the `<a2ui-surface>` component, you must enable custom elements rendering by setting the `enableCustomElements` property to `true`. This allows custom components registered via the component registry to be rendered.
+
+### Web (Lit)
+
+```typescript
+// Get reference to the surface element
+const surfaceElement = document.querySelector('a2ui-surface');
+
+// Enable custom elements
+surfaceElement.enableCustomElements = true;
+
+// Set other required properties
+surfaceElement.surfaceId = 'main';
+surfaceElement.surface = surface;
+surfaceElement.processor = processor;
+```
+
+**Important**: Without setting `enableCustomElements = true`, custom components will not render, even if they are properly registered in the component registry.
+
+### Why This is Required
+
+The A2UI `Surface` component wraps the `Root` component, which handles the actual rendering. The `enableCustomElements` property controls whether the Root component should look up and instantiate custom elements from the component registry. By default, this is `false` to ensure only standard A2UI components are rendered unless explicitly enabled.
+
 ## Defining Custom Catalogs
 
 TODO: Add detailed guide for defining custom catalogs for each platform.