Enable custom elements through Surface component

[shahabl]

Description

This PR adds support for custom elements when using the <a2ui-surface> component by exposing the enableCustomElements property.

Problem

The A2UI Root component has an enableCustomElements property that allows custom elements registered via componentRegistry to be rendered. However, the Surface component (which wraps Root) did not expose this property. This meant that when using <a2ui-surface> as the top-level component, it was impossible to enable custom element rendering.

Solution

• Added enableCustomElements property declaration to the Surface component
• Propagated the property from Surface to the Root component in the render template

This is a minimal, non-breaking change that enables the existing custom element functionality to work through the Surface component.

Use Case

Applications using <a2ui-surface> can now register and render custom components alongside standard A2UI components by setting:

surfaceElement.enableCustomElements = true;

Pre-launch Checklist

• I signed the CLA.
• I read the Contributors Guide.
• I read the Style Guide.
• I have added updates to the CHANGELOG.
• I updated/added relevant documentation.
• My code changes (if any) have tests.

If you need help, consider asking for advice on the discussion board.

[gemini-code-assist]

Code Review

This pull request correctly adds the enableCustomElements property to the Surface component and passes it to the underlying Root component, enabling custom element rendering when using <a2ui-surface>. The change is minimal and effective. My review focuses on improving project quality by adding tests and documentation for this new feature, as per the repository guidelines. I've also noted from the PR checklist that the changelog should be updated.

[gemini-code-assist]

This new property enables key functionality for the Surface component. Based on the repository's style guide (line 17), new code changes should include tests. Please add a unit test to verify that custom elements are correctly rendered when enableCustomElements is set to true on an <a2ui-surface> component.

References

1. If there are code changes, code should have tests. ^(link)

[shahabl]

The existing test suite (model.test.ts) focuses on the data processing layer and
doesn't include UI component rendering tests. UI component tests would require browser
globals (DOM, CustomEvent, HTMLElement, etc.) and a test environment setup (like
jsdom or happy-dom).

[zeroasterisk]

Thanks for the clean PR, @shahabl.

Before this lands, I want to flag that v0.9 of the spec (now finalized in specification/v0_9/) replaces the enableCustomElements pattern entirely. In v0.9, custom catalog support is handled through the required catalogId field on createSurface:

{
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "mycompany.com:restaurant-catalog"
  }
}

The renderer resolves components from whatever catalog the agent declares — no boolean flag needed. This is by design: catalog negotiation is a first-class protocol concept, not a renderer config toggle.

My recommendation: We should not merge a v0.8-only API addition that v0.9 explicitly supersedes. Instead:

1. The docs addition to custom-components.md is valuable — but it should document the v0.9 catalogId approach as the primary path, with v0.8 enableCustomElements noted as legacy.
2. The Lit renderer change itself is fine as a v0.8 backport, but the Surface component will need to support catalogId-based catalog resolution for v0.9 regardless — that's the change worth investing in.

Would you be open to updating this PR to target the v0.9 catalog mechanism? Happy to point you to the relevant spec files (specification/v0_9/json/server_to_client.json and specification/v0_9/docs/a2ui_protocol.md).

[shahabl]

Thanks for the clean PR, @shahabl.

Before this lands, I want to flag that v0.9 of the spec (now finalized in specification/v0_9/) replaces the enableCustomElements pattern entirely. In v0.9, custom catalog support is handled through the required catalogId field on createSurface:

Thank you for the feedback @zeroasterisk. I'll update the PR as suggested.

[zeroasterisk]

Thanks for this docs improvement, @shahabl! The enableCustomElements property is easy to miss and worth documenting clearly. 🙏

The code change in this PR (adding @property decorator for enableCustomElements in surface.ts) was already present in main. The docs section you've added to custom-components.md is still missing from the current docs — if you'd like to submit just that documentation update as a fresh PR against the current docs structure, it would be a valuable addition! Closing this as the code portion is superseded and the docs need a fresh targeted PR.