Merge branch 'main' into feat/generic-a2ui-react-renderer

Signed-off-by: Yuzuru Tanahashi <75597583+sugoi-yuzuru@users.noreply.github.com>

Author: sugoi-yuzuru

.agents/skills/a2ui-agent-maintenance/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: a2ui-implement-new-sdks-for-client-language
+description: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.
+---
+
+# A2UI SDK Implementation Guide (Phased Execution)
+
+This skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.
+
+---
+
+## **1. Core State SDK Phases**
+
+If you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:
+
+### **Phase 1: Context & Schemas Ingestion**
+
+Thoroughly review:
+
+- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).
+- `specification/v1_0/json/common_types.json` (dynamic binding schemas).
+- `specification/v1_0/json/server_to_client.json` (message envelopes).
+- `specification/v1_0/catalogs/basic/catalog.json` (target components catalog).
+
+### **Phase 2: Technical Architecture Planning**
+
+Create a detailed, local architectural proposal detailing:
+
+- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).
+- **Component APIs**: How will you define the `ComponentApi` interface in this language?
+- **Binding Strategy**: How will you structure the abstract Core Binder Layer?
+- _STOP and obtain human reviewer approval on this plan before writing code._
+
+### **Phase 3: Core Model Layer**
+
+Implement the framework-agnostic data and processor layers:
+
+1.  **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.
+2.  **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.
+3.  **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.
+4.  **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.
+5.  **Context Mapping**: Implement `DataContext` and `ComponentContext`.
+6.  **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.
+7.  **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.
+
+### **Phase 4: Foundational Basic Catalog Support**
+
+Bootstrap support for the Basic Catalog:
+
+- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.
+- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.
+- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.
+
+### **Phase 5: Complete Basic Catalog Support**
+
+- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.
+- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.
+- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.
+
+---
+
+## **2. Framework Adapter SDK Phases**
+
+If you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:
+
+### **Phase 1: Ingestion & Core Integration**
+
+Review:
+
+- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).
+- `specification/v1_0/docs/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).
+
+### **Phase 2: Architectural Plan**
+
+Draft a plan specifying:
+
+- **Component Registry**: How components are dynamically resolved and instantiated.
+- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.
+- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.
+- _STOP and obtain human reviewer approval on this plan._
+
+### **Phase 3: Adapter & Lifecycle Layer**
+
+- Implement `ComponentImplementation` base traits/classes.
+- Implement the framework-native `Surface` entrypoint widget.
+- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.
+
+### **Phase 4: Bootstrapping Basic Catalog Rendering**
+
+- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.
+- Bundle these elements into the first framework catalog adapter.
+- Verify reactive layout properties dynamically.
+
+### **Phase 5: Gallery Application Milestone**
+
+Build the **Gallery App** as a testing playground with:
+
+- Left Column: Sample navigation.
+- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.
+- Right Column: Live data model inspect pane and action logger.
+- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.
+- _STOP and obtain human reviewer approval of the UI and visual rendering performance._
+
+### **Phase 6: Full Catalog Support**
+
+- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.
+- Update the Gallery App to support all official examples in `specification/v1_0/catalogs/basic/examples/`.
+- Run visual parity and event action tests to verify correctness.

.agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md

@@ -40,7 +40,7 @@ _Note: There is no P4 priority tier. Issues that are out of scope, highly custom
 ### 2. Feature Requests
 
 - **Analysis**:
-  - Verify if the request aligns with the [A2UI roadmap](../../../../docs/roadmap.md) and/or design philosophy for the affected components. Be lenient if the idea can be implemented entirely as a client-side catalog extension or a custom renderer component without modifying the core protocol schemas or SDK interfaces.
+  - Verify if the request aligns with the [A2UI roadmap](../../../../docs/public/roadmap.md) and/or design philosophy for the affected components. Be lenient if the idea can be implemented entirely as a client-side catalog extension or a custom renderer component without modifying the core protocol schemas or SDK interfaces.
   - Note if the request seems to be related to a specific issue or PR that has already been discussed.
 - **Action**:
   - If aligned, set action to `backlog` with priority `P2` or `P3` and suggest appropriate component labels (e.g., `component: standard catalog specification`, `type: feature/enhancement`).
@@ -50,10 +50,10 @@ _Note: There is no P4 priority tier. Issues that are out of scope, highly custom
 
 - **Analysis**:
   - Identify if the issue is a question about usage or setup rather than a bug.
-  - If the question is answered in the documentation (e.g., [quickstart.md](../../../../docs/quickstart.md)), provide a link to the relevant guide in the response.
+  - If the question is answered in the documentation (e.g., [quickstart.md](../../../../docs/public/quickstart.md)), provide a link to the relevant guide in the response.
 - **Action**:
   - Set action to `close_resolved` or `close_invalid`.
-  - Answer the question directly or provide links to the relevant guides (e.g., [quickstart.md](../../../../docs/quickstart.md)) or GitHub Discussions, then close the issue.
+  - Answer the question directly or provide links to the relevant guides (e.g., [quickstart.md](../../../../docs/public/quickstart.md)) or GitHub Discussions, then close the issue.
 
 ---
 

.agents/skills/a2ui-issue-triage/references/triage_criteria.md

@@ -0,0 +1,42 @@
+---
+name: Bug Report
+about: Report a bug or issue in the codebase
+title: '[BUG]: '
+labels: bug
+assignees: ''
+---
+
+- [ ] I have searched the existing issues to make sure this bug has not already been reported.
+
+## Describe the Bug
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Screenshots / Video / Logs
+
+If applicable, add screenshots, video recordings, or console logs to help explain the problem.
+
+## Environment Details
+
+- **OS**: [e.g. macOS, Ubuntu, Windows]
+- **Browser/Platform**: [e.g. Chrome, Safari, Node.js version, Python version]
+- **SDK/Package Name & Version**: [e.g. a2ui-agent v0.9.0, Lit v0.8.0]
+- **Protocol Version**: [e.g. v0.9, v0.10]
+- **Agent Framework & LLM Model**: [e.g. ADK / Gemini 1.5 Pro, CopilotKit / GPT-4o]
+
+## Additional Context
+
+Add any other context or logs about the problem here.

.agents/skills/a2ui-sdk-design/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: Documentation Improvement
+about: Propose improvements or report errors in the documentation
+title: '[DOCS]: '
+labels: documentation
+assignees: ''
+---
+
+- [ ] I have searched the existing issues to make sure this documentation issue has not already been reported.
+
+## Problem Page(s)
+
+Which page(s) or file(s) in the documentation have problems? (Include URLs or file paths)
+
+## Describe the Issue
+
+What is incorrect, outdated, unclear, or missing?
+
+## Proposed Changes
+
+How would you suggest improving the documentation? Feel free to provide the exact phrasing or a draft of the changes.
+
+## Additional Context
+
+Any other information or comments.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest an idea or enhancement for this project
+title: '[FEATURE]: '
+labels: enhancement
+assignees: ''
+---
+
+- [ ] I have searched the existing issues to make sure this feature has not already been requested.
+
+## Is your feature request related to a problem? Please describe.
+
+A clear and concise description of what the problem is. (e.g. "I'm always frustrated when...")
+
+## Describe the Proposed Solution
+
+A clear and concise description of what you want to happen.
+
+## Describe Alternatives Considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, mockup designs, or details about the feature request here.

.github/ISSUE_TEMPLATE/documentation.md

@@ -83,11 +83,12 @@ jobs:
 
       - name: Copy schemas to documentation
         run: |
-          cp -R specification/* docs/specification/
+          mkdir -p docs/public/specification/
+          cp -R specification/* docs/public/specification/
           # Flatten JSON files to version roots to support clean URLs without redirects
           for version in v0_8 v0_9 v0_9_1 v1_0; do
-            if [ -d "docs/specification/$version/json" ]; then
-              cp docs/specification/$version/json/*.json docs/specification/$version/
+            if [ -d "docs/public/specification/$version/json" ]; then
+              cp docs/public/specification/$version/json/*.json docs/public/specification/$version/
             fi
           done
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,50 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Validate A2UI Blueprints
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "blueprints/**"
+      - ".github/workflows/validate_blueprints.yml"
+  pull_request:
+    paths:
+      - "blueprints/**"
+      - ".github/workflows/validate_blueprints.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate-blueprints:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+
+      - name: Run Blueprint Validator
+        run: python3 blueprints/validate_blueprints.py

.github/workflows/docs.yml

@@ -85,6 +85,13 @@ jobs:
         with:
           persist-credentials: false
       - uses: ./.github/actions/setup-node
+      - name: Set up JDK 21
+        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5.3.0
+        with:
+          java-version: "21"
+          distribution: "temurin"
+      - name: Install Playwright browsers
+        run: npx playwright@1.58.1 install --with-deps chromium chromium-headless-shell
       - name: Setup Wireit Cache
         uses: google/wireit@9d7c2e5346f8ef1b1ab6014c4e96c74e234f7ed5 # setup-github-actions-caching/v2.0.4
       - name: Build Renderers