docs(showcase): a2ui-fixed-schema cross-framework parity via WhenFrameworkHas

Closes the architectural-divergence gap for a2ui-fixed-schema across
4 frameworks. Pairs with PDX-68 — the canonical docs page now renders
the correct code + prose per framework idiom.

Code regions added:
- spring-ai DisplayFlightTool.java: wraps inline FLIGHT_SCHEMA with
  @region[backend-schema-json-load]
- ms-agent-dotnet A2uiFixedSchemaAgent.cs: same name wrapping the inline
  C# FlightSchema array
- mastra src/mastra/tools/index.ts: wraps generateA2uiTool with
  @region[backend-render-operations] (LLM-driven path)
- strands src/agents/agent.py: same on the generate_a2ui @tool

MDX (fixed-schema.mdx) restructure:
- Intro neutralized; new 3-bullet rundown of which frameworks fall into
  schema-loading / schema-inline / llm-driven
- 'How it works' step 1 reworded to be framework-neutral
- Steps 4 + 5 split into three <WhenFrameworkHas a2ui_pattern=...> gates:
  schema-loading → 'Load the schema JSON at startup' + render ops
  schema-inline  → 'Define the schema inline' + render ops
  llm-driven     → single 'Generate the schema dynamically' step

Spot-checked on dev server:
- /langgraph-python/.../fixed-schema → shows schema-loading section only
- /spring-ai/.../fixed-schema → shows schema-inline section only
- /mastra/.../fixed-schema → shows llm-driven section only
- /crewai-crews/.../fixed-schema → shows schema-loading section only

Author: samjulien

showcase/integrations/mastra/src/mastra/tools/index.ts

@@ -145,6 +145,14 @@ export const searchFlightsTool = createTool({
   execute: async ({ flights }) => JSON.stringify(searchFlightsImpl(flights)),
 });
 
+// @region[backend-render-operations]
+// The `generate-a2ui` tool runs a secondary LLM call with a forced
+// `render_a2ui` tool, then converts that tool call's args into the
+// A2UI `a2ui_operations` container that the middleware forwards to
+// the frontend renderer. Mastra returns the operations as a JSON
+// string from the tool body; the catalog
+// (`copilotkit://generative-catalog`) resolves component names to
+// React renderers on the client.
 export const generateA2uiTool = createTool({
   id: "generate-a2ui",
   description: "Generate dynamic A2UI surface components",
@@ -197,3 +205,4 @@ export const generateA2uiTool = createTool({
     );
   },
 });
+// @endregion[backend-render-operations]

showcase/integrations/ms-agent-dotnet/agent/A2uiFixedSchemaAgent.cs

@@ -69,9 +69,14 @@ public AIAgent Create()
             ]);
     }
 
-    // The fixed-schema flight component tree. Frontend renders this via a
-    // registered catalog (`copilotkit://flight-fixed-catalog`). Matches the
-    // LangGraph reference at src/agents/a2ui_schemas/flight_schema.json.
+    // @region[backend-schema-json-load]
+    // The fixed-schema flight component tree. .NET doesn't ship a
+    // JSON-loading helper analogous to LangGraph Python's
+    // `a2ui.load_schema(...)`, so the schema is declared inline as a
+    // C# array — equivalent to deserialising a `flight_schema.json`
+    // file at startup. Matches the LangGraph reference at
+    // `src/agents/a2ui_schemas/flight_schema.json`. Frontend renders
+    // this via the registered catalog (`copilotkit://flight-fixed-catalog`).
     private static readonly object[] FlightSchema = new object[]
     {
         new { id = "root", component = "Card", child = "content" },
@@ -121,6 +126,7 @@ public AIAgent Create()
         },
         new { id = "bookButtonLabel", component = "Text", text = "Book flight" },
     };
+    // @endregion[backend-schema-json-load]
 
     // @region[backend-render-operations]
     [Description("Show a flight card for the given trip. Use short airport codes (e.g. SFO, JFK) for origin/destination and a price string like $289.")]

showcase/integrations/spring-ai/src/main/java/com/copilotkit/showcase/springai/tools/DisplayFlightTool.java

@@ -25,6 +25,13 @@ public class DisplayFlightTool implements Function<DisplayFlightTool.Request, St
 
     public record Request(String origin, String destination, String airline, String price) {}
 
+    // @region[backend-schema-json-load]
+    // The fixed-schema flight component tree. Spring AI doesn't ship a
+    // JSON-loading helper analogous to `a2ui.load_schema(...)`, so the
+    // schema is declared inline as a Java constant — equivalent to
+    // deserialising a `flight_schema.json` file at startup. The frontend
+    // catalog (`copilotkit://flight-fixed-catalog`) resolves each
+    // `component` name to a React renderer.
     private static final List<Map<String, Object>> FLIGHT_SCHEMA = List.of(
             Map.of("id", "root", "component", "Card", "child", "content"),
             Map.of("id", "content", "component", "Column",
@@ -58,6 +65,7 @@ public record Request(String origin, String destination, String airline, String
                     )),
             Map.of("id", "bookButtonLabel", "component", "Text", "text", "Book flight")
     );
+    // @endregion[backend-schema-json-load]
 
     @Override
     public String apply(Request request) {

showcase/integrations/strands/src/agents/agent.py

@@ -155,6 +155,14 @@ def search_flights(flights: list[dict]):
     return json.dumps(result)
 
 
+# @region[backend-render-operations]
+# The `generate_a2ui` tool runs a secondary LLM call with a forced
+# `render_a2ui` tool, then converts that tool call's args into the
+# A2UI `a2ui_operations` container via
+# `build_a2ui_operations_from_tool_call`. The ag_ui_strands middleware
+# detects the container in the tool result and forwards the ops to
+# the frontend, which resolves component names through the registered
+# catalog (`copilotkit://generative-catalog`).
 @tool
 def generate_a2ui(context: str) -> str:
     """Generate dynamic A2UI components based on the conversation.
@@ -273,6 +281,7 @@ def generate_a2ui(context: str) -> str:
 
     result = build_a2ui_operations_from_tool_call(args)
     return json.dumps(result)
+# @endregion[backend-render-operations]
 
 
 @tool

showcase/shell-docs/src/content/docs/generative-ui/a2ui/fixed-schema.mdx

@@ -8,18 +8,34 @@ snippet_cell: a2ui-fixed-schema
 
 In the fixed-schema approach, you design the UI schema once (by hand,
 or using the [A2UI Composer](https://a2ui-composer.ag-ui.com/)) and
-save it as JSON next to your agent. The agent tool only provides the
-*data*; the surface appears instantly when the tool returns because
-nothing has to be generated at runtime.
+keep it on the agent side. The agent tool only provides the *data*;
+the surface appears instantly when the tool returns because nothing
+has to be generated at runtime.
+
+How the schema is *delivered* to the runtime is the only thing that
+varies between integrations:
+
+- **Schema-loading** (langgraph-python, langgraph-typescript,
+  langgraph-fastapi, llamaindex, crewai-crews, pydantic-ai,
+  ms-agent-python, google-adk) — the schema is saved as a `.json`
+  file next to the agent and loaded once at startup.
+- **Schema-inline** (spring-ai, ms-agent-dotnet) — the schema is
+  declared inline as a typed literal in source. The host language
+  doesn't ship a `load_schema` JSON loader, so the structure is
+  compiled in directly.
+- **LLM-driven** (mastra, strands) — the agent runs a secondary LLM
+  call to produce the operations container per-request. The catalog
+  is still fixed; the schema is generated on demand.
 
 Ask about a flight and the agent renders a fully structured card from a pre-defined schema:
 
 <InlineDemo demo="a2ui-fixed-schema" />
 
 ## How it works
 
-1. The schema is loaded from a JSON file at startup via
-   `a2ui.load_schema(...)`, a thin `json.load` wrapper.
+1. The schema is made available to the agent — either loaded from a
+   JSON file at startup, declared inline, or generated per-request,
+   depending on the integration.
 2. The agent's `display_flight` tool receives data from the primary LLM
    (origin / destination / airline / price).
 3. The tool returns `a2ui.render(...)` with `createSurface` +
@@ -28,7 +44,7 @@ Ask about a flight and the agent renders a fully structured card from a pre-defi
    renders the surface using the matching 5-component client catalog
    (Title, Airport, Arrow, AirlineBadge, PriceTag, plus the built-ins).
 
-## Schemas as JSON: compositional trees
+## Compositional schemas
 
 The example below ships a flight card assembled compositionally from
 small sub-components rather than one monolithic `FlightCard`:
@@ -42,7 +58,8 @@ Card
      └─ Button       (Book)
 ```
 
-That tree lives in `backend/schemas/flight_schema.json`. Components
+That tree lives backend-side — as a JSON file, an inline literal, or
+a per-request LLM output, depending on the integration. Components
 without data bindings (like `Title` or `Arrow`) carry their value
 inline; components bound to the LLM's data (like `Airport`) reference
 fields via JSON Pointer paths such as `{ "path": "/origin" }`. The
@@ -86,28 +103,71 @@ renderers with CopilotKit's built-ins so the schema can reference
 <Snippet region="catalog-creation" />
 </Step>
 
+<WhenFrameworkHas flag="a2ui_pattern" equals="schema-loading">
 <Step>
 ### Load the schema JSON at startup
 
-`a2ui.load_schema(path)` is a thin `json.load` wrapper that parses the
-schema file once at module-import time. The sibling `booked_schema.json`
-is kept ready for the button-click "booked" optimistic swap (see the
-note on action handlers below):
+`a2ui.load_schema(path)` (or the framework's equivalent thin `json.load`
+wrapper) parses the schema file once at module-import time. The
+sibling `booked_schema.json` is kept ready for the button-click
+"booked" optimistic swap (see the note on action handlers below):
 
 <Snippet region="backend-schema-json-load" />
 </Step>
 
 <Step>
 ### Return render operations from the tool
 
-The `display_flight` tool returns `a2ui.render(operations=[…])`. The
-A2UI middleware detects the operations container in the tool result
-and forwards it to the frontend renderer. The LLM only generates the
-four data fields (`origin`, `destination`, `airline`, `price`); the
-schema does the rest:
+The agent tool returns `a2ui.render(operations=[…])`. The A2UI
+middleware detects the operations container in the tool result and
+forwards it to the frontend renderer. The LLM only generates the four
+data fields (`origin`, `destination`, `airline`, `price`); the schema
+does the rest:
 
 <Snippet region="backend-render-operations" />
 </Step>
+</WhenFrameworkHas>
+
+<WhenFrameworkHas flag="a2ui_pattern" equals="schema-inline">
+<Step>
+### Define the schema inline
+
+Spring AI / .NET don't ship a `load_schema` JSON helper, so the
+component tree is declared inline as a typed literal in source —
+equivalent to deserialising a `flight_schema.json` but compiled into
+the agent class. The structure is identical to the JSON form; only
+the surface syntax changes:
+
+<Snippet region="backend-schema-json-load" />
+</Step>
+
+<Step>
+### Return render operations from the tool
+
+The agent tool builds the same `createSurface` + `updateComponents` +
+`updateDataModel` operations container and returns it. The A2UI
+middleware detects the operations in the tool result and forwards
+them to the frontend renderer; the LLM only supplies the four data
+fields:
+
+<Snippet region="backend-render-operations" />
+</Step>
+</WhenFrameworkHas>
+
+<WhenFrameworkHas flag="a2ui_pattern" equals="llm-driven">
+<Step>
+### Generate the schema dynamically
+
+Mastra and Strands take a different route: the agent tool runs a
+*secondary* LLM call with a forced tool choice that produces the
+operations container per-request. The frontend catalog is still fixed
+(same `Title`/`Airport`/`Arrow`/`AirlineBadge`/`PriceTag` primitives),
+but the schema is built on the fly. Schema construction and render
+emission happen in the same tool call:
+
+<Snippet region="backend-render-operations" />
+</Step>
+</WhenFrameworkHas>
 </Steps>
 
 ## Why compositional beats monolithic