docs(showcase/spring-ai): region markers across 13 cells

Per-framework region pass on spring-ai. 13 cells advanced from B (regions
missing) to A (ready). Same patterns as mastra (CopilotKit#4326), smalls batch 1
(CopilotKit#4361), ms-agent (CopilotKit#4363), and google-adk (CopilotKit#4369).

Cells covered (28 regions):
- agentic-chat: provider-setup + configure-suggestions in-place; chat-component sibling
- chat-customization-css: css-variables (theme.css) + theme-css-import
- chat-slots: register-welcome-slot + register-disclaimer-slot + register-assistant-message-slot
- frontend-tools: frontend-tool-handler + frontend-tool-registration
- headless-simple: use-agent-simple + message-list-simple sibling (production carries deduplicateMessages QA logic against the AG-UI Spring AI adapter's multi-run tool-call loop)
- open-gen-ui: minimal-provider-setup + minimal-runtime-flag (route.ts)
- open-gen-ui-advanced: advanced-runtime-config (route.ts, shared file with open-gen-ui)
- prebuilt-popup: popup-basic-setup
- prebuilt-sidebar: sidebar-basic-setup + sidebar-configuration
- readonly-state-agent-context: context-provider-sketch + use-agent-context-call
- shared-state-read-write: use-agent-read + use-agent-write (page.tsx) + notes-card-render + preferences-card-render
- subagents: delegation-log-frontend (frontend) + subagent-setup + supervisor-delegation-tools (Java backend, SubagentsController.java already in highlight)
- a2ui-fixed-schema: backend-render-operations on tools/DisplayFlightTool.java

Sibling teaching files (Java backend, distinct from Python/TS frameworks):
- agentic-chat/chat-component.snippet.tsx — production Chat carries QA hooks (useFrontendTool / useRenderTool / useAgentContext + data-testid) irrelevant to the prebuilt-chat docs page
- headless-simple/headless-chat.snippet.tsx — production carries deduplicateMessages defensive logic; sibling exposes a clean useAgent + agent.messages.map teaching surface

Deferred:
- a2ui-fixed-schema::backend-schema-json-load — spring-ai keeps the schema inline as Java List.of(Map.of(...)) in DisplayFlightTool.java rather than loading from a JSON file. Same divergence as ms-agent-dotnet (CopilotKit#4363); the docs region's "load JSON at startup" framing doesn't match.
- declarative-gen-ui::runtime-inject-tool — cross-cutting; tracked in PDX-70.

Backend region markers use Java syntax `// @region[name]` / `// @endregion[name]`.

Test plan:
- [ ] `npx tsx showcase/scripts/bundle-demo-content.ts` succeeds; all 28 regions resolve in `demo-content.json` (verified locally — re-audit shows only deferred items remaining)
- [ ] localhost shell-docs spot-check `/spring-ai/prebuilt-components/chat` — chat-component snippet renders the minimal Chat from the sibling file
- [ ] localhost shell-docs spot-check `/spring-ai/headless/simple` — use-agent-simple + message-list-simple resolve from the sibling file (no dedup noise in the docs surface)
- [ ] localhost shell-docs spot-check `/spring-ai/multi-agent/subagents` — delegation-log-frontend + subagent-setup + supervisor-delegation-tools resolve; backend snippet shows spring-ai's idiom (ToolCallback factory + ChatClient.builder) rather than langgraph's @tool/create_agent pattern
- [ ] localhost shell-docs spot-check `/spring-ai/state/shared-state-read-write` — all four regions resolve including the multi-file pair from notes-card.tsx + preferences-card.tsx
- [ ] localhost shell-docs spot-check `/spring-ai/generative-ui/a2ui/fixed-schema` — backend-render-operations resolves; backend-schema-json-load remains yellow (deferred per above)

Author: samjulien

showcase/integrations/spring-ai/src/app/api/copilotkit-ogui/route.ts

@@ -36,13 +36,24 @@ export const POST = async (req: NextRequest) => {
     const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
       endpoint: "/api/copilotkit-ogui",
       serviceAdapter: new ExperimentalEmptyAdapter(),
+      // @region[minimal-runtime-flag]
+      // @region[advanced-runtime-config]
+      // Server-side config is identical for the minimal and advanced cells —
+      // the advanced behaviour (sandbox -> host function calls) is wired
+      // entirely on the frontend via `openGenerativeUI.sandboxFunctions` on
+      // the provider. The single `openGenerativeUI` flag below turns on
+      // Open Generative UI for the listed agent(s); the runtime middleware
+      // converts each agent's streamed `generateSandboxedUi` tool call into
+      // `open-generative-ui` activity events.
       runtime: new CopilotRuntime({
         // @ts-ignore -- see main route.ts
         agents,
         openGenerativeUI: {
           agents: ["open-gen-ui", "open-gen-ui-advanced"],
         },
       }),
+      // @endregion[advanced-runtime-config]
+      // @endregion[minimal-runtime-flag]
     });
     return await handleRequest(req);
   } catch (error: unknown) {

showcase/integrations/spring-ai/src/app/demos/agentic-chat/chat-component.snippet.tsx

@@ -0,0 +1,28 @@
+// Docs-only snippet — not imported or rendered. The actual route is served
+// by page.tsx, which carries QA hooks (frontend tools, render tools, agent
+// context) that aren't relevant to the prebuilt-chat docs page. This file
+// gives the docs a minimal Chat definition to point at via the
+// chat-component region without disturbing the runtime demo.
+//
+// Why a sibling file: the bundler walks every file in the demo folder and
+// extracts region markers from each, so a docs-targeted teaching example
+// can live alongside the production demo without being wired into the
+// route. See: showcase/scripts/bundle-demo-content.ts.
+
+import {
+  CopilotChat,
+  useConfigureSuggestions,
+} from "@copilotkit/react-core/v2";
+
+// @region[chat-component]
+export function Chat() {
+  useConfigureSuggestions({
+    suggestions: [
+      { title: "Write a sonnet", message: "Write a short sonnet about AI." },
+    ],
+    available: "always",
+  });
+
+  return <CopilotChat agentId="agentic_chat" className="h-full rounded-2xl" />;
+}
+// @endregion[chat-component]

showcase/integrations/spring-ai/src/app/demos/agentic-chat/page.tsx

@@ -13,9 +13,11 @@ import { z } from "zod";
 
 export default function AgenticChatDemo() {
   return (
+    // @region[provider-setup]
     <CopilotKit runtimeUrl="/api/copilotkit" agent="agentic_chat">
       <Chat />
     </CopilotKit>
+    // @endregion[provider-setup]
   );
 }
 
@@ -68,6 +70,7 @@ function Chat() {
     },
   });
 
+  // @region[configure-suggestions]
   useConfigureSuggestions({
     suggestions: [
       {
@@ -81,6 +84,7 @@ function Chat() {
     ],
     available: "always",
   });
+  // @endregion[configure-suggestions]
 
   return (
     <div

showcase/integrations/spring-ai/src/app/demos/chat-customization-css/page.tsx

@@ -9,7 +9,9 @@
 
 import React from "react";
 import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
+// @region[theme-css-import]
 import "./theme.css";
+// @endregion[theme-css-import]
 
 export default function ChatCustomizationCssDemo() {
   return (

showcase/integrations/spring-ai/src/app/demos/chat-customization-css/theme.css

@@ -6,6 +6,8 @@
  * https://docs.copilotkit.ai/custom-look-and-feel/customize-built-in-ui-components
  */
 
+/* @region[css-variables] */
+/* CopilotKit CSS variable overrides (accent colors, etc.) */
 .chat-css-demo-scope {
   --copilot-kit-primary-color: #ff006e;
   --copilot-kit-contrast-color: #ffffff;
@@ -16,6 +18,7 @@
   --copilot-kit-separator-color: #ff006e;
   --copilot-kit-muted-color: #c2185b;
 }
+/* @endregion[css-variables] */
 
 .chat-css-demo-scope .copilotKitMessages {
   font-family: "Georgia", "Cambria", "Times New Roman", serif;

showcase/integrations/spring-ai/src/app/demos/chat-slots/page.tsx

@@ -32,12 +32,18 @@ function Chat() {
     available: "always",
   });
 
+  // @region[register-welcome-slot]
   const welcomeScreen = CustomWelcomeScreen;
+  // @endregion[register-welcome-slot]
+  // @region[register-disclaimer-slot]
   const input = { disclaimer: CustomDisclaimer };
+  // @endregion[register-disclaimer-slot]
+  // @region[register-assistant-message-slot]
   const messageView = {
     assistantMessage:
       CustomAssistantMessage as unknown as typeof CopilotChatAssistantMessage,
   };
+  // @endregion[register-assistant-message-slot]
 
   return (
     <CopilotChat

showcase/integrations/spring-ai/src/app/demos/frontend-tools/page.tsx

@@ -22,6 +22,7 @@ function Chat() {
     "var(--copilot-kit-background-color)",
   );
 
+  // @region[frontend-tool-registration]
   useFrontendTool({
     name: "change_background",
     description:
@@ -31,14 +32,17 @@ function Chat() {
         .string()
         .describe("The CSS background value. Prefer gradients."),
     }),
+    // @region[frontend-tool-handler]
     handler: async ({ background }: { background: string }) => {
       setBackground(background);
       return {
         status: "success",
         message: `Background changed to ${background}`,
       };
     },
+    // @endregion[frontend-tool-handler]
   });
+  // @endregion[frontend-tool-registration]
 
   useConfigureSuggestions({
     suggestions: [

showcase/integrations/spring-ai/src/app/demos/headless-simple/headless-chat.snippet.tsx

@@ -0,0 +1,131 @@
+// Docs-only snippet — not imported or rendered. The actual route is served
+// by page.tsx, which carries a `deduplicateMessages` pass to defend against
+// the Spring AI AG-UI adapter's multi-run tool-call loop (see the comment
+// on that helper in page.tsx). That dedup logic is QA scaffolding, not part
+// of the headless-chat teaching content. This file gives the docs a clean
+// minimal surface to point at via `use-agent-simple` and
+// `message-list-simple` regions without the dedup distraction.
+//
+// Why a sibling file: the bundler walks every file in the demo folder and
+// extracts region markers from each, so a docs-targeted teaching example
+// can live alongside the production demo without being wired into the
+// route. See: showcase/scripts/bundle-demo-content.ts.
+
+import React, { useState } from "react";
+import {
+  useAgent,
+  useComponent,
+  useCopilotKit,
+  useRenderToolCall,
+} from "@copilotkit/react-core/v2";
+import { z } from "zod";
+
+function ShowCard({ title, body }: { title: string; body: string }) {
+  return (
+    <div className="my-2 rounded-lg border border-gray-300 bg-white p-4 shadow-sm">
+      <div className="font-semibold text-gray-900">{title}</div>
+      <div className="mt-1 text-sm text-gray-700 whitespace-pre-wrap">
+        {body}
+      </div>
+    </div>
+  );
+}
+
+export function HeadlessChat() {
+  // @region[use-agent-simple]
+  const { agent } = useAgent({ agentId: "headless-simple" });
+  const { copilotkit } = useCopilotKit();
+  const [input, setInput] = useState("");
+
+  useComponent({
+    name: "show_card",
+    description: "Display a titled card with a short body of text.",
+    parameters: z.object({
+      title: z.string().describe("Short heading for the card."),
+      body: z.string().describe("Body text for the card."),
+    }),
+    render: ShowCard,
+  });
+
+  const renderToolCall = useRenderToolCall();
+  // @endregion[use-agent-simple]
+
+  const send = () => {
+    const text = input.trim();
+    if (!text || agent.isRunning) return;
+    agent.addMessage({
+      id: crypto.randomUUID(),
+      role: "user",
+      content: text,
+    });
+    void copilotkit.runAgent({ agent }).catch(() => {});
+    setInput("");
+  };
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-col gap-2 rounded-xl border border-gray-200 bg-white p-4 min-h-[300px]">
+        {/* @region[message-list-simple] */}
+        {agent.messages.length === 0 && (
+          <div className="text-sm text-gray-400">No messages yet. Say hi!</div>
+        )}
+        {agent.messages.map((m) => {
+          if (m.role === "user") {
+            return (
+              <div
+                key={m.id}
+                data-message-role="user"
+                className="self-end rounded-lg bg-blue-600 px-3 py-2 text-white max-w-[80%]"
+              >
+                {typeof m.content === "string" ? m.content : ""}
+              </div>
+            );
+          }
+          if (m.role === "assistant") {
+            const toolCalls =
+              "toolCalls" in m && Array.isArray(m.toolCalls) ? m.toolCalls : [];
+            return (
+              <div
+                key={m.id}
+                data-message-role="assistant"
+                className="self-start max-w-[90%]"
+              >
+                {m.content && (
+                  <div className="rounded-lg bg-gray-100 px-3 py-2 text-gray-900">
+                    {m.content as React.ReactNode}
+                  </div>
+                )}
+                {toolCalls.map((tc: { id: string }) => (
+                  <div key={tc.id}>
+                    {renderToolCall({ toolCall: tc as any })}
+                  </div>
+                ))}
+              </div>
+            );
+          }
+          return null;
+        })}
+        {agent.isRunning && (
+          <div className="text-xs text-gray-400">Agent is thinking...</div>
+        )}
+        {/* @endregion[message-list-simple] */}
+      </div>
+      <div className="flex gap-2">
+        <textarea
+          className="flex-1 rounded-lg border border-gray-300 p-2 text-sm"
+          rows={2}
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+        <button
+          className="rounded-lg bg-blue-600 px-4 py-2 text-white text-sm font-medium disabled:opacity-50"
+          onClick={send}
+          disabled={agent.isRunning || !input.trim()}
+        >
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}

showcase/integrations/spring-ai/src/app/demos/open-gen-ui/page.tsx

@@ -84,6 +84,12 @@ const minimalSuggestions = [
 
 export default function OpenGenUiDemo() {
   return (
+    // @region[minimal-provider-setup]
+    // Minimal Open Generative UI frontend: the built-in activity renderer is
+    // registered by CopilotKitProvider, so a plain <CopilotChat /> is enough —
+    // no custom tool renderers, no activity-renderer registration.
+    // We DO pass `openGenerativeUI.designSkill` to swap in visualisation-tuned
+    // guidance in place of the default shadcn design skill.
     <CopilotKit
       runtimeUrl="/api/copilotkit-ogui"
       agent="open-gen-ui"
@@ -95,6 +101,7 @@ export default function OpenGenUiDemo() {
         </div>
       </div>
     </CopilotKit>
+    // @endregion[minimal-provider-setup]
   );
 }
 

showcase/integrations/spring-ai/src/app/demos/prebuilt-popup/page.tsx

@@ -9,6 +9,7 @@ import {
 
 export default function PrebuiltPopupDemo() {
   return (
+    // @region[popup-basic-setup]
     <CopilotKit runtimeUrl="/api/copilotkit" agent="prebuilt-popup">
       <MainContent />
       <CopilotPopup
@@ -20,6 +21,7 @@ export default function PrebuiltPopupDemo() {
       />
       <Suggestions />
     </CopilotKit>
+    // @endregion[popup-basic-setup]
   );
 }