Merge branch 'main' into add-react-renderer

Author: lukasmoschitz

.gemini/GEMINI.md

@@ -25,6 +25,7 @@ The A2UI repository is organized into several key directories:
     -   `java/`: Java implementation of the A2UI agent library.
 -   `renderers/`: Contains renderer libraries.
     -   `lit/`: The shared Lit renderer library used by the Lit clients.
+    -   `web_core/`: The shared core library used by Lit and Angular renderers.
 -   `tools/`: Helper tools for development.
     -   `editor/`: A web-based editor for generating and visualizing A2UI.
     -   `inspector/`: A web-based inspector for A2UI responses.
@@ -69,9 +70,13 @@ Ensure you have your environment variables set up (create a `.env` file if neces
 The Lit clients are located in `samples/client/lit/`.
 
 1.  **Build the Renderer**:
-    First, ensure the shared renderer is built:
+    First, ensure the shared renderers are built:
     ```bash
-    cd renderers/lit
+    cd renderers/web_core
+    npm install
+    npm run build
+
+    cd ../lit
     npm install
     npm run build
     ```
@@ -88,6 +93,18 @@ The Lit clients are located in `samples/client/lit/`.
 
 The Angular clients are located in `samples/client/angular/`.
 
+First, ensure the shared renderers are built (if not already done):
+```bash
+cd renderers/web_core
+npm install
+npm run build
+
+cd ../lit
+npm install
+npm run build
+```
+
+Then run the Angular client:
 ```bash
 cd samples/client/angular
 npm install

.github/workflows/docs.yml

@@ -69,6 +69,12 @@ jobs:
       - name: Install documentation dependencies
         run: pip install -r requirements-docs.txt
 
+      - name: Validate documentation conversion script
+        run: pip install pytest && pytest docs/scripts/test_convert_docs.py
+
+      - name: Convert Admonitions in Documentation
+        run: python docs/scripts/convert_docs.py --mode github-to-mkdocs
+
       - name: Build Documentation (PR Check)
         if: github.event_name == 'pull_request'
         run: mkdocs build

.github/workflows/editor_build.yml

@@ -19,11 +19,13 @@ on:
     paths:
       - 'tools/editor/**'
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/editor_build.yml'
   pull_request:
     paths:
       - 'tools/editor/**'
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/editor_build.yml'
 
 jobs:
@@ -38,6 +40,14 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install web_core deps
+        working-directory: ./renderers/web_core
+        run: npm ci
+
+      - name: Build web_core
+        working-directory: ./renderers/web_core
+        run: npm run build
+
       - name: Install lib's deps
         working-directory: ./renderers/lit
         run: npm ci

.github/workflows/inspector_build.yml

@@ -20,11 +20,13 @@ on:
     paths:
       - 'tools/inspector/**'
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/inspector_build.yml'
   pull_request:
     paths:
       - 'tools/inspector/**'
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/inspector_build.yml'
 
 jobs:
@@ -39,6 +41,14 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install web_core deps
+        working-directory: ./renderers/web_core
+        run: npm ci
+
+      - name: Build web_core
+        working-directory: ./renderers/web_core
+        run: npm run build
+
       - name: Install lib's deps
         working-directory: ./renderers/lit
         run: npm ci

.github/workflows/lit_samples_build.yml

@@ -35,6 +35,14 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install web_core deps
+        working-directory: ./renderers/web_core
+        run: npm ci
+
+      - name: Build web_core
+        working-directory: ./renderers/web_core
+        run: npm run build
+
       - name: Install lib's deps
         working-directory: ./renderers/lit
         run: npm i

.github/workflows/ng_build_and_test.yml

@@ -35,6 +35,14 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install web_core dependencies
+        working-directory: ./renderers/web_core
+        run: npm i
+
+      - name: Build web_core
+        working-directory: ./renderers/web_core
+        run: npm run build
+
       - name: Install web lib deps
         working-directory: ./renderers/lit
         run: npm i

.github/workflows/web_build_and_test.yml

@@ -19,10 +19,12 @@ on:
     branches: [ main ]
     paths:
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/web_build_and_test.yml'
   pull_request:
     paths:
       - 'renderers/lit/**'
+      - 'renderers/web_core/**'
       - '.github/workflows/web_build_and_test.yml'
 
 jobs:
@@ -37,6 +39,14 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install web_core dependencies
+        working-directory: ./renderers/web_core
+        run: npm i
+
+      - name: Build web_core
+        working-directory: ./renderers/web_core
+        run: npm run build
+
       - name: Install Lit renderer dependencies
         working-directory: ./renderers/lit
         run: npm i

.gitignore

@@ -5,6 +5,7 @@ dist
 .env
 .idx
 .vscode
+.idea
 __pycache__
 *.pyc
 .angular

README.md

@@ -9,7 +9,7 @@ to generate or populate rich user interfaces.
 
 *A gallery of A2UI rendered cards, showing a variety of UI compositions that A2UI can achieve.*
 
-## ⚠️ Status: Early Stage Public Preview
+## ⚠️ Status: Early stage public preview
 
 > **Note:** A2UI is currently in **v0.8 (Public Preview)**. The specification and
 implementations are functional but are still evolving. We are opening the project to
@@ -30,7 +30,7 @@ component library (Flutter, Angular, Lit, etc.).
 This approach ensures that agent-generated UIs are
 **safe like data, but expressive like code**.
 
-## High-Level Philosophy
+## High-level philosophy
 
 A2UI was designed to address the specific challenges of interoperable,
 cross-platform, generative or template-based UI responses from agents.
@@ -63,7 +63,7 @@ places security firmly in the developer's hands, enabling them to enforce
 strict sandboxing policies and "trust ladders" directly within their custom
 component logic rather than relying solely on the core system.
 
-## Use Cases
+## Use cases
 
 Some of the use cases include:
 
@@ -98,7 +98,7 @@ A2UI is designed to be a lightweight format, but it fits into a larger ecosystem
 * **Host Frameworks:** Requires a host application built in a supported framework
 (currently: Web or Flutter).
 
-## Getting Started
+## Getting started
 
 The best way to understand A2UI is to run the samples.
 
@@ -108,7 +108,7 @@ The best way to understand A2UI is to run the samples.
 * Python (for agent samples)
 * A valid [Gemini API Key](https://aistudio.google.com/) is required for the samples.
 
-### Running the Restaurant Finder Demo
+### Running the Restaurant Finder demo
 
 1. **Clone the repository:**
 
@@ -117,7 +117,7 @@ The best way to understand A2UI is to run the samples.
     cd A2UI
     ```
 
-2. **Set your API Key:**
+2. **Set your API key:**
 
     ```bash
     export GEMINI_API_KEY="your_gemini_api_key"
@@ -134,8 +134,13 @@ The best way to understand A2UI is to run the samples.
     Open a new terminal window:
 
     ```bash
+    # Install and build the Web Core library
+    cd renderers/web_core
+    npm install
+    npm run build
+
     # Install and build the Lit renderer
-    cd renderers/lit
+    cd ../lit
     npm install
     npm run build
 
@@ -155,10 +160,10 @@ to try out as well.
 
 We hope to work with the community on the following:
 
-* **Spec Stabilization:** Moving towards a v1.0 specification.
-* **More Renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
-* **Additional Transports:** Support for REST and more.
-* **Additional Agent Frameworks:** Genkit, LangGraph, and more.
+* **Spec stabilization:** Moving towards a v1.0 specification.
+* **More renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
+* **Additional transports:** Support for REST and more.
+* **Additional Agent frameworks:** Genkit, LangGraph, and more.
 
 ## Contribute
 

a2a_agents/python/a2ui_agent/README.md

@@ -1,16 +1,16 @@
-# A2UI Agent Implementation
+# A2UI Agent implementation
 
 The `a2a_agents/python/a2ui_agent/` is the Python implementation of the a2ui agent library.
 
-### Extension Components (`src/a2ui/extension`)
+### Extension components (`src/a2ui/extension`)
 
 The `src/a2ui/extension` directory contains the core logic for the A2UI agent extension:
 
 *   **`a2ui_extension.py`**: Core utilities for extension management and A2UI part handling.
 *   **`a2ui_schema_utils.py`**: Schema manipulation helpers.
 *   **`send_a2ui_to_client_toolset.py`**: An example implementation of using ADK toolcalls to implement A2UI.
 
-## Running Tests
+## Running tests
 
 1. Navigate to the a2ui_agent dir:
 
@@ -40,4 +40,4 @@ All operational data received from an external agent—including its AgentCard,
 
 Similarly, any UI definition or data stream received must be treated as untrusted. Malicious agents could attempt to spoof legitimate interfaces to deceive users (phishing), inject malicious scripts via property values (XSS), or generate excessive layout complexity to degrade client performance (DoS). If your application supports optional embedded content (such as iframes or web views), additional care must be taken to prevent exposure to malicious external sites.
 
-Developer Responsibility: Failure to properly validate data and strictly sandbox rendered content can introduce severe vulnerabilities. Developers are responsible for implementing appropriate security measures—such as input sanitization, Content Security Policies (CSP), strict isolation for optional embedded content, and secure credential handling—to protect their systems and users.
+Developer Responsibility: Failure to properly validate data and strictly sandbox rendered content can introduce severe vulnerabilities. Developers are responsible for implementing appropriate security measures—such as input sanitization, Content Security Policies (CSP), strict isolation for optional embedded content, and secure credential handling—to protect their systems and users.