Merge S1: stub auto-load via PartialLoader

Author: samjulien

docs/content/docs/integrations/a2a/generative-ui/declarative-a2ui.mdx

@@ -58,11 +58,11 @@ Build an A2A agent, configure it to use A2UI, use the A2UI composer to generate
       ...
       ---BEGIN SINGLE_COLUMN_LIST_EXAMPLE---
       [
-        {{ "beginRendering": {{ "surfaceId": "default", "root": "root-column", "styles": {{ "primaryColor": "#FF0000", "font": "Roboto" }} }} }},
-        {{ "surfaceUpdate": {{
+        {{ "createSurface": {{ "surfaceId": "default", "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json", "styles": {{ "primaryColor": "#FF0000", "font": "Roboto" }} }} }},
+        {{ "updateComponents": {{
           "surfaceId": "default",
           "components": [
-            {{ "id": "root-column", "component": {{ "Column": {{ "children": {{ "explicitList": ["title-heading", "item-list"] }} }} }} }},
+            {{ "id": "root", "component": {{ "Column": {{ "children": {{ "explicitList": ["title-heading", "item-list"] }} }} }} }},
             {{ "id": "title-heading", "component": {{ "Text": {{ "usageHint": "h1", "text": {{ "literalString": "Top Restaurants" }} }} }} }},
             {{ "id": "item-list", "component": {{ "List": {{ "direction": "vertical", "children": {{ "template": {{ "componentId": "item-card-template", "dataBinding": "/items" }} }} }} }} }},
             {{ "id": "item-card-template", "component": {{ "Card": {{ "child": "card-layout" }} }} }},
@@ -77,7 +77,7 @@ Build an A2A agent, configure it to use A2UI, use the A2UI composer to generate
             {{ "id": "book-now-text", "component": {{ "Text": {{ "text": {{ "literalString": "Book Now" }} }} }} }}
           ]
         }} }},
-        {{ "dataModelUpdate": {{
+        {{ "updateDataModel": {{
           "surfaceId": "default",
           "path": "/",
           "contents": [
@@ -109,9 +109,9 @@ Build an A2A agent, configure it to use A2UI, use the A2UI composer to generate
     The widgets are injected into the agent's prompt, in this case using the `RESTAURANT_UI_EXAMPLES` variable.
     Widgets are defined for the agent using examples of the json arrays they should output, wrapped in a comment block.
     - A comment indicating the start of the example
-    - beginRendering: The start of the widget's rendering
-    - surfaceUpdate: An example of the json structure for the widget
-    - dataModelUpdate: an example of the data that will be used to populate the widget
+    - createSurface: Initializes the surface with its catalog (and optional styles/theme). Must come first.
+    - updateComponents: The component tree for the widget. Exactly one component must have `id: "root"`.
+    - updateDataModel: The data used to populate the widget
     - A comment indicating the end of the example
 
     In the example repo, all of the widgets are defined in a single variable int the prompt_builder.py file, but you can structure them however you like,

docs/content/docs/integrations/deepagents/generative-ui/a2ui/advanced.mdx

@@ -174,8 +174,8 @@ useA2UIActionHandler((action, declaredOps) => {
   if (action.name === "book_flight") {
     // Return custom operations
     return [
-      { surfaceUpdate: { surfaceId: action.surfaceId, components: mySchema } },
-      { beginRendering: { surfaceId: action.surfaceId, root: "root" } },
+      { createSurface: { surfaceId: action.surfaceId, catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json" } },
+      { updateComponents: { surfaceId: action.surfaceId, components: mySchema } },
     ];
   }
   return null; // skip — let other handlers or fallback try

docs/content/docs/integrations/deepagents/generative-ui/a2ui/dynamic-schema.mdx

@@ -116,8 +116,8 @@ The secondary LLM's `render_a2ui` tool call streams through LangGraph as `TOOL_C
 
 1. Extracts the `components` array as it streams — waits for the full schema before rendering
 2. Extracts `surfaceId` and `root` from the partial JSON
-3. Once the schema is complete, emits `surfaceUpdate` + `beginRendering`
-4. Extracts complete `items` objects progressively and emits `dataModelUpdate` for each
+3. Once the schema is complete, emits `createSurface` + `updateComponents`
+4. Extracts complete `items` objects progressively and emits `updateDataModel` for each
 5. Cards appear one by one as data streams in
 
 ## Built-in progress indicator

docs/content/docs/integrations/deepagents/generative-ui/a2ui/fixed-schema.mdx

@@ -12,7 +12,7 @@ In the fixed-schema approach, you design the UI schema once (in a JSON file or u
 
 1. Schema is loaded from a JSON file at startup
 2. Agent tool receives data from the LLM (e.g., flight search results)
-3. Tool returns `a2ui.render()` with surfaceUpdate + dataModelUpdate + beginRendering
+3. Tool returns `a2ui.render()` with createSurface + updateComponents + updateDataModel
 4. The A2UI middleware intercepts the tool result and renders the surface
 
 ## Implementation
@@ -65,23 +65,22 @@ def search_flights(flights: list[Flight]) -> str:
     """Search for flights and display results as rich cards."""
     return a2ui.render(
         operations=[
-            a2ui.surface_update(SURFACE_ID, FLIGHT_SCHEMA),
-            a2ui.data_model_update(SURFACE_ID, {"flights": flights}),
-            a2ui.begin_rendering(SURFACE_ID, "root"),
+            a2ui.create_surface(SURFACE_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(SURFACE_ID, {"flights": flights}),
         ],
         action_handlers={
             # Exact match: fires when a button with action.name="book_flight" is clicked
             "book_flight": [
-                a2ui.surface_update(SURFACE_ID, BOOKED_SCHEMA),
-                a2ui.data_model_update(SURFACE_ID, {
+                a2ui.update_components(SURFACE_ID, BOOKED_SCHEMA),
+                a2ui.update_data_model(SURFACE_ID, {
                     "title": "Booking Confirmed",
                     "detail": "Your flight has been booked.",
                 }),
-                a2ui.begin_rendering(SURFACE_ID, "root"),
             ],
             # Catch-all: fires for any button action without a specific match
             "*": [
-                a2ui.data_model_update(SURFACE_ID, {
+                a2ui.update_data_model(SURFACE_ID, {
                     "status": "Action received",
                 }),
             ],

docs/content/docs/integrations/deepagents/generative-ui/a2ui/index.mdx

@@ -60,21 +60,21 @@ All three approaches use the same A2UI protocol and renderer. The difference is
 
 ## How it works
 
-Every A2UI surface is built from three operations:
+Every A2UI v0.9 surface is built from three operations:
 
-1. **`surfaceUpdate`** — defines the component tree (the schema)
-2. **`dataModelUpdate`** — provides the data that populates the components
-3. **`beginRendering`** — tells the client to start rendering
+1. **`createSurface`** — initializes the surface with its catalog (must come first)
+2. **`updateComponents`** — defines the component tree (the schema)
+3. **`updateDataModel`** — provides the data that populates the components
 
 The CopilotKit Python SDK provides helpers to build these operations:
 
 ```python
 from copilotkit import a2ui
 
-a2ui.surface_update(surface_id, components)
-a2ui.data_model_update(surface_id, {"items": data})
-a2ui.begin_rendering(surface_id, root_id)
-a2ui.render(operations)  # wraps and serializes
+a2ui.create_surface(surface_id)
+a2ui.update_components(surface_id, components)
+a2ui.update_data_model(surface_id, {"items": data})
+a2ui.render(operations)  # wraps in a2ui_operations and serializes
 ```
 
 Continue to one of the approach guides above to see the full implementation.

docs/content/docs/integrations/langgraph/generative-ui/a2ui/advanced.mdx

@@ -174,8 +174,8 @@ useA2UIActionHandler((action, declaredOps) => {
   if (action.name === "book_flight") {
     // Return custom operations
     return [
-      { surfaceUpdate: { surfaceId: action.surfaceId, components: mySchema } },
-      { beginRendering: { surfaceId: action.surfaceId, root: "root" } },
+      { createSurface: { surfaceId: action.surfaceId, catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json" } },
+      { updateComponents: { surfaceId: action.surfaceId, components: mySchema } },
     ];
   }
   return null; // skip — let other handlers or fallback try

docs/content/docs/integrations/langgraph/generative-ui/a2ui/dynamic-schema.mdx

@@ -115,8 +115,8 @@ The secondary LLM's `render_a2ui` tool call streams through LangGraph as `TOOL_C
 
 1. Extracts the `components` array as it streams — waits for the full schema before rendering
 2. Extracts `surfaceId` and `root` from the partial JSON
-3. Once the schema is complete, emits `surfaceUpdate` + `beginRendering`
-4. Extracts complete `items` objects progressively and emits `dataModelUpdate` for each
+3. Once the schema is complete, emits `createSurface` + `updateComponents`
+4. Extracts complete `items` objects progressively and emits `updateDataModel` for each
 5. Cards appear one by one as data streams in
 
 ## Built-in progress indicator

docs/content/docs/integrations/langgraph/generative-ui/a2ui/fixed-schema.mdx

@@ -12,7 +12,7 @@ In the fixed-schema approach, you design the UI schema once (in a JSON file or u
 
 1. Schema is loaded from a JSON file at startup
 2. Agent tool receives data from the LLM (e.g., flight search results)
-3. Tool returns `a2ui.render()` with surfaceUpdate + dataModelUpdate + beginRendering
+3. Tool returns `a2ui.render()` with createSurface + updateComponents + updateDataModel
 4. The A2UI middleware intercepts the tool result and renders the surface
 
 ## Implementation
@@ -65,23 +65,22 @@ def search_flights(flights: list[Flight]) -> str:
     """Search for flights and display results as rich cards."""
     return a2ui.render(
         operations=[
-            a2ui.surface_update(SURFACE_ID, FLIGHT_SCHEMA),
-            a2ui.data_model_update(SURFACE_ID, {"flights": flights}),
-            a2ui.begin_rendering(SURFACE_ID, "root"),
+            a2ui.create_surface(SURFACE_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(SURFACE_ID, {"flights": flights}),
         ],
         action_handlers={
             # Exact match: fires when a button with action.name="book_flight" is clicked
             "book_flight": [
-                a2ui.surface_update(SURFACE_ID, BOOKED_SCHEMA),
-                a2ui.data_model_update(SURFACE_ID, {
+                a2ui.update_components(SURFACE_ID, BOOKED_SCHEMA),
+                a2ui.update_data_model(SURFACE_ID, {
                     "title": "Booking Confirmed",
                     "detail": "Your flight has been booked.",
                 }),
-                a2ui.begin_rendering(SURFACE_ID, "root"),
             ],
             # Catch-all: fires for any button action without a specific match
             "*": [
-                a2ui.data_model_update(SURFACE_ID, {
+                a2ui.update_data_model(SURFACE_ID, {
                     "status": "Action received",
                 }),
             ],

docs/content/docs/integrations/langgraph/generative-ui/a2ui/index.mdx

@@ -60,21 +60,21 @@ All three approaches use the same A2UI protocol and renderer. The difference is
 
 ## How it works
 
-Every A2UI surface is built from three operations:
+Every A2UI v0.9 surface is built from three operations:
 
-1. **`surfaceUpdate`** — defines the component tree (the schema)
-2. **`dataModelUpdate`** — provides the data that populates the components
-3. **`beginRendering`** — tells the client to start rendering
+1. **`createSurface`** — initializes the surface with its catalog (must come first)
+2. **`updateComponents`** — defines the component tree (the schema)
+3. **`updateDataModel`** — provides the data that populates the components
 
 The CopilotKit Python SDK provides helpers to build these operations:
 
 ```python
 from copilotkit import a2ui
 
-a2ui.surface_update(surface_id, components)
-a2ui.data_model_update(surface_id, {"items": data})
-a2ui.begin_rendering(surface_id, root_id)
-a2ui.render(operations)  # wraps and serializes
+a2ui.create_surface(surface_id)
+a2ui.update_components(surface_id, components)
+a2ui.update_data_model(surface_id, {"items": data})
+a2ui.render(operations)  # wraps in a2ui_operations and serializes
 ```
 
 Continue to one of the approach guides above to see the full implementation.

showcase/harness/src/probes/drivers/e2e-deep.ts

@@ -220,6 +220,16 @@ export interface E2eDeepPage extends Page {
    * gracefully when a renderer crash closes the page underneath them.
    */
   isClosed?(): boolean;
+  /**
+   * Resolve a Playwright Locator for the given CSS selector. The probe
+   * scripts use it for count-based assertions
+   * (`page.locator(sel).count()`) when polling for an expected number of
+   * elements to appear; the harness `Page.evaluate` path only supports
+   * zero-arg functions, so dynamic selectors need a Locator. Optional so
+   * test fakes can omit it; the only production probe that needs it is
+   * `d5-tool-rendering-reasoning-chain`.
+   */
+  locator?(selector: string): { count(): Promise<number> };
   /**
    * Install a request interceptor on the underlying Playwright page.
    * Optional — only the d5-readonly-state-context probe currently uses
@@ -426,6 +436,7 @@ const defaultLauncher: E2eDeepBrowserLauncher =
                 requestFailures: requestFailures.slice(-10),
               }),
               isClosed: () => page.isClosed(),
+              locator: (s) => page.locator(s),
               route: (url, handler) =>
                 page.route(url, handler as Parameters<typeof page.route>[1]),
               unroute: (url) => page.unroute(url),
@@ -547,6 +558,7 @@ export function createPooledE2eDeepLauncher(
                 requestFailures: requestFailures.slice(-10),
               }),
               isClosed: () => page.isClosed(),
+              locator: (s) => page.locator(s),
               route: (url, handler) =>
                 page.route(url, handler as Parameters<typeof page.route>[1]),
               unroute: (url) => page.unroute(url),