@genui/a3-create 0.1.36

package/template/app/components/organisms/StateViewer.tsx

@@ -0,0 +1,126 @@
+'use client'
+
+import { useState } from 'react'
+import { Paper, Typography, Box, List, ListItemButton, ListItemText, Collapse } from '@mui/material'
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore'
+import ChevronRightIcon from '@mui/icons-material/ChevronRight'
+import { STATE_HEADING, STATE_EMPTY } from '@constants/ui'
+
+interface StateViewerProps {
+  state: Record<string, unknown>
+}
+
+const VALUE_COLORS = {
+  string: '#16a34a',
+  number: '#2563eb',
+  boolean: '#ea580c',
+  null: '#9ca3af',
+} as const
+
+function ValueDisplay({ value }: { value: unknown }) {
+  const isNullish = value === null || value === undefined
+  const typeKey = isNullish ? 'null' : typeof value
+  const color = typeKey in VALUE_COLORS ? VALUE_COLORS[typeKey as keyof typeof VALUE_COLORS] : '#64748b'
+
+  const getContent = () => {
+    if (value === null) return 'null'
+    if (value === undefined) return 'undefined'
+    if (typeof value === 'string') return `"${value}"`
+    if (typeof value === 'object') return JSON.stringify(value)
+    if (typeof value === 'function') return `[Function${value.name ? `: ${value.name}` : ''}]`
+    if (typeof value === 'symbol') return value.toString()
+    return String(value as number | boolean | bigint)
+  }
+
+  return (
+    <Typography
+      component="span"
+      sx={{ color, fontFamily: 'monospace', fontSize: 13, fontStyle: isNullish ? 'italic' : 'normal' }}
+    >
+      {getContent()}
+    </Typography>
+  )
+}
+
+function StateNode({ label, value, defaultOpen = false, depth = 0 }: { label: string; value: unknown; defaultOpen?: boolean; depth?: number }) {
+  const [open, setOpen] = useState(defaultOpen)
+
+  const isExpandable = value !== null && typeof value === 'object'
+
+  if (!isExpandable) {
+    return (
+      <ListItemButton sx={{ pl: 2 + depth * 2, py: 0.25 }} disableRipple>
+        <ListItemText
+          primary={
+            <Box sx={{ display: 'flex', gap: 1, alignItems: 'center' }}>
+              <Typography component="span" sx={{ fontFamily: 'monospace', fontSize: 13, fontWeight: 600, color: '#475569' }}>
+                {label}:
+              </Typography>
+              <ValueDisplay value={value} />
+            </Box>
+          }
+        />
+      </ListItemButton>
+    )
+  }
+
+  const entries = Array.isArray(value)
+    ? value.map((v, i) => [String(i), v] as [string, unknown])
+    : Object.entries(value as Record<string, unknown>)
+
+  return (
+    <>
+      <ListItemButton onClick={() => setOpen(!open)} sx={{ pl: 2 + depth * 2, py: 0.25 }}>
+        {open ? <ExpandMoreIcon sx={{ fontSize: 18, color: '#94a3b8' }} /> : <ChevronRightIcon sx={{ fontSize: 18, color: '#94a3b8' }} />}
+        <ListItemText
+          primary={
+            <Box sx={{ display: 'flex', gap: 1, alignItems: 'center', ml: 0.5 }}>
+              <Typography component="span" sx={{ fontFamily: 'monospace', fontSize: 13, fontWeight: 600, color: '#475569' }}>
+                {label}
+              </Typography>
+              <Typography component="span" sx={{ fontFamily: 'monospace', fontSize: 12, color: '#94a3b8' }}>
+                {Array.isArray(value) ? `[${value.length}]` : `{${entries.length}}`}
+              </Typography>
+            </Box>
+          }
+        />
+      </ListItemButton>
+      <Collapse in={open} timeout="auto" unmountOnExit>
+        <List disablePadding>
+          {entries.map(([key, val]) => (
+            <StateNode key={key} label={key} value={val} depth={depth + 1} />
+          ))}
+        </List>
+      </Collapse>
+    </>
+  )
+}
+
+export function StateViewer({ state }: StateViewerProps) {
+  const entries = Object.entries(state)
+  const hasData = entries.length > 0
+
+  return (
+    <Paper
+      elevation={0}
+      sx={{ p: 2, border: 1, borderColor: 'divider', borderRadius: 3, overflow: 'hidden', display: 'flex', flexDirection: 'column' }}
+    >
+      <Typography variant="subtitle2" fontWeight="bold" gutterBottom>
+        {STATE_HEADING}
+      </Typography>
+      <Box sx={{ overflowY: 'auto', maxHeight: 300 }}>
+        {hasData ? (
+          <List disablePadding dense>
+            {entries.map(([key, value]) => (
+              <StateNode key={key} label={key} value={value} defaultOpen depth={0} />
+            ))}
+          </List>
+        ) : (
+          <Typography variant="body2" sx={{ color: 'text.secondary', py: 2, textAlign: 'center', fontStyle: 'italic' }}>
+            {STATE_EMPTY}
+          </Typography>
+        )}
+      </Box>
+    </Paper>
+  )
+}

package/template/app/components/organisms/StreamChat.tsx

@@ -0,0 +1,173 @@
+'use client'
+
+import { useState, useCallback, useRef } from 'react'
+import { Typography } from '@mui/material'
+import { ChatMessageList } from '@organisms/ChatMessageList'
+import { ChatContainer, ChatHeader } from '@atoms'
+import { ChatInput } from '@molecules'
+import { MessageSender } from '@genui/a3'
+import type { Message } from '@genui/a3'
+import { EventType } from '@ag-ui/client'
+import { CHAT_ERROR, CHAT_ERROR_SHORT, CHAT_TRANSITION } from '@constants/ui'
+import { useRestart, type RestartResult } from '@lib/hooks/useRestart'
+
+type StreamEvent = {
+  type: EventType
+  delta?: string
+  agentId?: string
+  result?: Record<string, unknown>
+  message?: string
+  content?: string
+  name?: string
+  value?: Record<string, unknown>
+}
+
+interface StreamChatProps {
+  sessionId: string
+  initialMessages?: Message[]
+  onSessionUpdate?: (update: { activeAgentId: string | null; state: Record<string, unknown> }) => void
+  onRestart?: () => Promise<RestartResult>
+}
+
+export function StreamChat({ sessionId, initialMessages, onSessionUpdate, onRestart }: StreamChatProps) {
+  const [messages, setMessages] = useState<Message[]>(initialMessages ?? [])
+  const [isLoading, setIsLoading] = useState(false)
+  const [isTransitioning, setIsTransitioning] = useState(false)
+  const assistantIdRef = useRef<string>('')
+  const { isRestarting, handleRestart } = useRestart({ onRestart, setMessages, onSessionUpdate })
+
+  const handleSubmit = useCallback(
+    async (text: string) => {
+      const userMsg: Message = {
+        messageId: crypto.randomUUID(),
+        text,
+        metadata: { source: MessageSender.USER },
+      }
+      setMessages((prev) => [...prev, userMsg])
+      setIsLoading(true)
+
+      // Create a placeholder assistant message for streaming into
+      let assistantId = crypto.randomUUID()
+      assistantIdRef.current = assistantId
+
+      const streamingMsg: Message = {
+        messageId: assistantId,
+        text: '',
+        metadata: { source: MessageSender.ASSISTANT },
+        isStreaming: true,
+      }
+      setMessages((prev) => [...prev, streamingMsg])
+
+      try {
+        const response = await fetch('/api/stream', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ message: text, sessionId }),
+        })
+
+        if (!response.ok) {
+          throw new Error(`HTTP error: ${response.status}`)
+        }
+
+        const reader = response.body?.getReader()
+        if (!reader) throw new Error('No response body')
+
+        const decoder = new TextDecoder()
+        let buffer = ''
+
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+
+          buffer += decoder.decode(value, { stream: true })
+
+          // Process complete SSE lines
+          const lines = buffer.split('\n')
+          buffer = lines.pop() ?? ''
+
+          for (const line of lines) {
+            if (!line.startsWith('data: ')) continue
+            const data = line.slice(6)
+            if (data === '[DONE]') continue
+
+            try {
+              const event = JSON.parse(data) as StreamEvent
+
+              if (event.type === EventType.TEXT_MESSAGE_CONTENT && event.delta) {
+                setIsTransitioning(false)
+                setMessages((prev) =>
+                  prev.map((m) => (m.messageId === assistantId ? { ...m, text: m.text + event.delta } : m)),
+                )
+              } else if (event.type === EventType.CUSTOM && event.name === 'AgentTransition') {
+                const transitionEvent = event as StreamEvent & {
+                  value?: { toAgentId?: string; state?: Record<string, unknown> }
+                }
+                onSessionUpdate?.({
+                  activeAgentId: transitionEvent.value?.toAgentId ?? null,
+                  state: transitionEvent.value?.state ?? {},
+                })
+                const prevAssistantId = assistantId
+                assistantId = crypto.randomUUID()
+                assistantIdRef.current = assistantId
+                setIsTransitioning(true)
+                setMessages((prev) => {
+                  const updated = prev.map((m) => (m.messageId === prevAssistantId ? { ...m, isStreaming: false } : m))
+                  return [
+                    ...updated,
+                    {
+                      messageId: assistantId,
+                      text: '',
+                      metadata: { source: MessageSender.ASSISTANT },
+                      isStreaming: true,
+                    },
+                  ]
+                })
+              } else if (event.type === EventType.RUN_FINISHED) {
+                setIsTransitioning(false)
+                const result = event.result
+                onSessionUpdate?.({
+                  activeAgentId: (result?.activeAgentId as string) ?? null,
+                  state: (result?.state as Record<string, unknown>) ?? {},
+                })
+                setMessages((prev) => prev.map((m) => (m.messageId === assistantId ? { ...m, isStreaming: false } : m)))
+              } else if (event.type === EventType.RUN_ERROR) {
+                setIsTransitioning(false)
+                setMessages((prev) =>
+                  prev.map((m) =>
+                    m.messageId === assistantId ? { ...m, text: m.text || CHAT_ERROR_SHORT, isStreaming: false } : m,
+                  ),
+                )
+              }
+            } catch {
+              // Skip malformed JSON lines
+            }
+          }
+        }
+
+        // Ensure streaming flag is cleared
+        setMessages((prev) => prev.map((m) => (m.messageId === assistantId ? { ...m, isStreaming: false } : m)))
+      } catch (error) {
+        console.error('Chat stream error:', error)
+        setMessages((prev) =>
+          prev.map((m) => (m.messageId === assistantId ? { ...m, text: m.text || CHAT_ERROR, isStreaming: false } : m)),
+        )
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [onSessionUpdate, sessionId],
+  )
+
+  return (
+    <ChatContainer elevation={0}>
+      <ChatHeader onRestart={() => void handleRestart?.()} isRestarting={isRestarting} />
+      <ChatMessageList messages={messages} />
+      {isTransitioning && (
+        <Typography variant="caption" color="textSecondary" sx={{ px: 2, pb: 1, fontStyle: 'italic' }}>
+          {CHAT_TRANSITION}
+        </Typography>
+      )}
+      <ChatInput onSubmit={handleSubmit} disabled={isLoading || isRestarting} />
+    </ChatContainer>
+  )
+}

package/template/app/components/organisms/index.ts

@@ -0,0 +1,10 @@
+export { AguiChat } from './AguiChat'
+export { AgentGraph } from './AgentGraph'
+export { Chat } from './Chat'
+export { ChatMessageList } from './ChatMessageList'
+export { ExamplePageLayout } from './ExamplePageLayout'
+export { OnboardingChat } from './OnboardingChat'
+export { Sidebar } from './Sidebar'
+export { SidebarLayout } from './SidebarLayout'
+export { StateViewer } from './StateViewer'
+export { StreamChat } from './StreamChat'

package/template/app/constants/chat.ts

@@ -0,0 +1,52 @@
+export const WELCOME_MESSAGE_TEXT = `Hi! I'm an A3 agent; one of potentially many that can be orchestrated together to build reliable, predictable applications.
+
+**Using an AI Coding Assistant?** Just paste this into your Ai prompt:
+
+\`\`\`text
+Ensure you carefully analyze and understand the instructions in @CLAUDE.md.
+I want to create a new project using A3 leveraging this initial "quick start" framework.
+\`\`\`
+
+**A3** is a TypeScript framework for building multi-agent (agentic) applications. It's not an autonomous tool or a computer-use assistant, it's a developer framework for orchestrating specialized agents that handle structured data, hand off to each other deterministically, and integrate with any LLM provider (AWS Bedrock, OpenAI, Anthropic, etc).
+
+Here's how A3 has been used in production:
+
+### Healthcare — Patient Intake & Booking
+
+A3 orchestrates a complex patient intake, triage, and booking flow using **16 specialized agents** that handle strictly validated, typed data payloads — gracefully handing off to one another without the confusion or hallucination of a single massive prompt, all backed securely by AWS DynamoDB:
+
+- **Pre-Triage Intake** → Verifies identity, routes to Illness or Injury Triage
+- **Illness / Injury Triage** → Assesses symptoms or injury details
+- **Visit Review** → Confirms clinic location
+- **Patient Review** → Validates demographic and clinical records
+- **Insurance Review** → Verifies medical coverage
+- **Payment** → Handles copays and balances
+- **Pick A Time** → Presents available scheduling slots
+- **Book Visit** → Commits the appointment
+- **Pharmacy Method** → Confirms prescription routing
+- **Summary & Wrap-Up** → Final instructions and session close
+
+Plus edge-case agents: Rejection Handler (ER reroutes), Urgent Care Guide (FAQs), Find User By Phone (SMS matching), and Survey (post-visit feedback).
+
+---
+
+Ask me anything about building with A3 — agents, transitions, providers, or getting started!
+`
+
+export const SESSION_IDS = {
+  ONBOARDING: 'onboarding',
+  EXAMPLES: {
+    BLOCKING: 'blocking',
+    STREAMING: 'streaming',
+    AGUI: 'agui',
+  },
+}
+
+const EXAMPLE_GREETING = `Hi there! I'm the **greeting agent**. What's your name?`
+
+export const SESSION_INITIAL_MESSAGES: Record<string, string> = {
+  [SESSION_IDS.ONBOARDING]: WELCOME_MESSAGE_TEXT,
+  [SESSION_IDS.EXAMPLES.BLOCKING]: EXAMPLE_GREETING,
+  [SESSION_IDS.EXAMPLES.STREAMING]: EXAMPLE_GREETING,
+  [SESSION_IDS.EXAMPLES.AGUI]: EXAMPLE_GREETING,
+}

package/template/app/constants/paths.ts

@@ -0,0 +1 @@
+export const REPO_URL = 'https://github.com/generalui/a3/blob/main'

package/template/app/constants/ui.ts

@@ -0,0 +1,61 @@
+// --- Metadata ---
+export const APP_TITLE = 'A3 Core Example'
+export const APP_DESCRIPTION = 'Example application for @genui/a3'
+
+// --- Navigation (Sidebar) ---
+export const NAV_HEADER = 'A3'
+export const NAV_HOME = 'Home'
+export const NAV_ONBOARDING = 'Onboarding'
+export const NAV_EXAMPLES = 'Examples'
+export const NAV_CHAT = 'Chat'
+export const NAV_STREAMING = 'Streaming'
+export const NAV_AGUI = 'AG-UI'
+
+// --- Onboarding ---
+export const ONBOARDING_TAGLINE =
+  '<strong>A3</strong> — Predictable, governable multi-agent orchestration for TypeScript.'
+
+// --- Examples Index ---
+export const EXAMPLES_HEADING = 'A3 Examples'
+export const EXAMPLES_SUBTITLE =
+  'Explore the different communication protocols and frontend implementations available in the A3 architecture.'
+export const EXAMPLES_CTA = 'Try it out'
+
+export const EXAMPLE_BLOCKING_TITLE = 'Blocking Chat'
+export const EXAMPLE_BLOCKING_DESCRIPTION =
+  "A synchronous (unary) chat implementation. The client waits for the agent to finish processing completely before rendering the response."
+export const EXAMPLE_STREAMING_TITLE = 'Streaming Chat'
+export const EXAMPLE_STREAMING_DESCRIPTION =
+  "A streaming response implementation using Server-Sent Events (SSE). The client renders the agent's response incrementally as it's being generated."
+export const EXAMPLE_AGUI_TITLE = 'AG-UI Protocol'
+export const EXAMPLE_AGUI_DESCRIPTION =
+  'Agentic UI implementation using the AG-UI protocol. The agent returns structured semantic events driving the client interface in real-time.'
+
+// --- Example Page Titles & Descriptions ---
+export const PAGE_BLOCKING_TITLE = 'A3 Example — Blocking Chat'
+export const PAGE_BLOCKING_DESCRIPTION =
+  "A greeting agent asks for your name. Once it has it, control passes to an age agent that asks for your age. You can ask to change your name at any time and you'll be handed back to the greeting agent. Each response arrives in full once the agent is done thinking."
+export const PAGE_STREAMING_TITLE = 'A3 Example — Streaming'
+export const PAGE_STREAMING_DESCRIPTION =
+  "A greeting agent asks for your name. Once it has it, control passes to an age agent that asks for your age. You can ask to change your name at any time and you'll be handed back to the greeting agent."
+export const PAGE_AGUI_TITLE = 'A3 Example — AG-UI Protocol'
+export const PAGE_AGUI_DESCRIPTION =
+  "A greeting agent asks for your name. Once it has it, control passes to an age agent that asks for your age. You can ask to change your name at any time and you'll be handed back to the greeting agent. Communication uses the AG-UI protocol, streaming structured events for text, transitions, and run lifecycle."
+
+// --- Chat UI ---
+export const CHAT_PLACEHOLDER = 'Type a message...'
+export const CHAT_SEND = 'Send'
+export const CHAT_RESTART = 'Restart session'
+export const CHAT_ERROR = 'Sorry, something went wrong. Please try again.'
+export const CHAT_ERROR_SHORT = 'Sorry, something went wrong.'
+export const CHAT_TRANSITION = 'Agent transition in progress...'
+
+// --- State Viewer ---
+export const STATE_HEADING = 'Session State'
+export const STATE_EMPTY = 'No state properties'
+
+// --- Agent Graph ---
+export const GRAPH_HEADING = 'Agent Graph'
+export const GRAPH_LEGEND_DETERMINISTIC = 'Deterministic'
+export const GRAPH_LEGEND_LLM = 'LLM-driven'
+export const GRAPH_ACTIVE_BADGE = 'Active'

package/template/app/examples/agui/page.tsx

@@ -0,0 +1,26 @@
+import { getChatSessionInstance } from '@agents'
+import { getAgentGraphData } from '@lib/getAgentGraphData'
+import { initRegistry } from '@agents/registry'
+import { SESSION_IDS } from '@constants/chat'
+import { PAGE_AGUI_TITLE, PAGE_AGUI_DESCRIPTION } from '@constants/ui'
+import { ExamplePageLayout } from '@organisms'
+
+export default async function AguiExample() {
+  initRegistry()
+  const agents = getAgentGraphData()
+  const session = getChatSessionInstance({ sessionId: SESSION_IDS.EXAMPLES.AGUI })
+  const sessionData = await session.getOrCreateSessionData()
+
+  return (
+    <ExamplePageLayout
+      title={PAGE_AGUI_TITLE}
+      description={PAGE_AGUI_DESCRIPTION}
+      sessionId={SESSION_IDS.EXAMPLES.AGUI}
+      initialMessages={sessionData.messages}
+      initialActiveAgentId={sessionData.activeAgentId}
+      initialState={sessionData.state}
+      variant="agui"
+      agents={agents}
+    />
+  )
+}

package/template/app/examples/chat/page.tsx

@@ -0,0 +1,26 @@
+import { getChatSessionInstance } from '@agents'
+import { getAgentGraphData } from '@lib/getAgentGraphData'
+import { initRegistry } from '@agents/registry'
+import { SESSION_IDS } from '@constants/chat'
+import { PAGE_BLOCKING_TITLE, PAGE_BLOCKING_DESCRIPTION } from '@constants/ui'
+import { ExamplePageLayout } from '@organisms'
+
+export default async function ChatExample() {
+  initRegistry()
+  const agents = getAgentGraphData()
+  const session = getChatSessionInstance({ sessionId: SESSION_IDS.EXAMPLES.BLOCKING })
+  const sessionData = await session.getOrCreateSessionData()
+
+  return (
+    <ExamplePageLayout
+      title={PAGE_BLOCKING_TITLE}
+      description={PAGE_BLOCKING_DESCRIPTION}
+      sessionId={SESSION_IDS.EXAMPLES.BLOCKING}
+      initialMessages={sessionData.messages}
+      initialActiveAgentId={sessionData.activeAgentId}
+      initialState={sessionData.state}
+      variant="blocking"
+      agents={agents}
+    />
+  )
+}

package/template/app/examples/page.tsx

@@ -0,0 +1,106 @@
+'use client'
+
+import Link from 'next/link'
+import { Typography, Card, CardActionArea, Container, Stack, Box } from '@mui/material'
+import ChatBubbleOutlineIcon from '@mui/icons-material/ChatBubbleOutline'
+import StreamIcon from '@mui/icons-material/Stream'
+import ExtensionIcon from '@mui/icons-material/Extension'
+import ArrowForwardIcon from '@mui/icons-material/ArrowForward'
+import {
+  EXAMPLES_HEADING,
+  EXAMPLES_SUBTITLE,
+  EXAMPLES_CTA,
+  EXAMPLE_BLOCKING_TITLE,
+  EXAMPLE_BLOCKING_DESCRIPTION,
+  EXAMPLE_STREAMING_TITLE,
+  EXAMPLE_STREAMING_DESCRIPTION,
+  EXAMPLE_AGUI_TITLE,
+  EXAMPLE_AGUI_DESCRIPTION,
+} from '@constants/ui'
+
+const EXAMPLES = [
+  {
+    title: EXAMPLE_BLOCKING_TITLE,
+    description: EXAMPLE_BLOCKING_DESCRIPTION,
+    href: '/examples/chat',
+    icon: <ChatBubbleOutlineIcon fontSize="large" />,
+    color: '#2563eb',
+    bgColor: 'rgba(37, 99, 235, 0.1)',
+  },
+  {
+    title: EXAMPLE_STREAMING_TITLE,
+    description: EXAMPLE_STREAMING_DESCRIPTION,
+    href: '/examples/stream',
+    icon: <StreamIcon fontSize="large" />,
+    color: '#9c27b0',
+    bgColor: 'rgba(156, 39, 176, 0.1)',
+  },
+  {
+    title: EXAMPLE_AGUI_TITLE,
+    description: EXAMPLE_AGUI_DESCRIPTION,
+    href: '/examples/agui',
+    icon: <ExtensionIcon fontSize="large" />,
+    color: '#2e7d32',
+    bgColor: 'rgba(46, 125, 50, 0.1)',
+  },
+]
+
+export default function ExamplesIndex() {
+  return (
+    <Box sx={{ flex: 1, p: 3, overflowY: 'auto' }}>
+      <Container maxWidth="lg" sx={{ mt: 5, mb: 10 }}>
+        <Stack spacing={3} alignItems="center" mb={10} textAlign="center">
+          <Typography variant="h3" fontWeight={800} color="text.primary">
+            {EXAMPLES_HEADING}
+          </Typography>
+          <Typography variant="h6" color="text.secondary" maxWidth="md">
+            {EXAMPLES_SUBTITLE}
+          </Typography>
+        </Stack>
+
+        <Stack direction={{ xs: 'column', md: 'row' }} spacing={4}>
+          {EXAMPLES.map((example) => (
+            <Card
+              key={example.href}
+              elevation={0}
+              sx={{
+                flex: 1,
+                border: 1,
+                borderColor: 'divider',
+                borderRadius: 4,
+                transition: '0.2s',
+                '&:hover': { borderColor: example.color, transform: 'translateY(-4px)', boxShadow: 4 },
+              }}
+            >
+              <CardActionArea
+                component={Link}
+                href={example.href}
+                sx={{
+                  p: 4,
+                  height: '100%',
+                  display: 'flex',
+                  flexDirection: 'column',
+                  alignItems: 'flex-start',
+                  gap: 2,
+                }}
+              >
+                <Box sx={{ p: 2, bgcolor: example.bgColor, color: example.color, borderRadius: 2 }}>
+                  {example.icon}
+                </Box>
+                <Typography variant="h5" fontWeight="bold">
+                  {example.title}
+                </Typography>
+                <Typography variant="body1" color="text.secondary" sx={{ flexGrow: 1 }}>
+                  {example.description}
+                </Typography>
+                <Stack direction="row" alignItems="center" gap={1} sx={{ color: example.color }} fontWeight="bold" mt={2}>
+                  {EXAMPLES_CTA} <ArrowForwardIcon fontSize="small" />
+                </Stack>
+              </CardActionArea>
+            </Card>
+          ))}
+        </Stack>
+      </Container>
+    </Box>
+  )
+}

package/template/app/examples/stream/page.tsx

@@ -0,0 +1,26 @@
+import { getChatSessionInstance } from '@agents'
+import { getAgentGraphData } from '@lib/getAgentGraphData'
+import { initRegistry } from '@agents/registry'
+import { SESSION_IDS } from '@constants/chat'
+import { PAGE_STREAMING_TITLE, PAGE_STREAMING_DESCRIPTION } from '@constants/ui'
+import { ExamplePageLayout } from '@organisms'
+
+export default async function StreamExample() {
+  initRegistry()
+  const agents = getAgentGraphData()
+  const session = getChatSessionInstance({ sessionId: SESSION_IDS.EXAMPLES.STREAMING })
+  const sessionData = await session.getOrCreateSessionData()
+
+  return (
+    <ExamplePageLayout
+      title={PAGE_STREAMING_TITLE}
+      description={PAGE_STREAMING_DESCRIPTION}
+      sessionId={SESSION_IDS.EXAMPLES.STREAMING}
+      initialMessages={sessionData.messages}
+      initialActiveAgentId={sessionData.activeAgentId}
+      initialState={sessionData.state}
+      variant="stream"
+      agents={agents}
+    />
+  )
+}

package/template/app/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">
+<defs>
+<style>
+@media (prefers-color-scheme: dark) {
+  .logo-mark { fill: #ffffff; }
+}
+</style>
+</defs>
+<g>
+<path class="logo-mark" d="M 560.50 870.11 C544.60,872.39 493.52,873.54 477.50,871.98 C429.64,867.32 381.89,853.57 340.50,832.53 C316.53,820.34 296.91,807.54 274.00,789.15 C261.51,779.12 236.58,754.18 225.88,741.00 C180.72,685.39 153.06,618.33 146.08,547.58 C144.70,533.59 144.69,497.56 146.06,483.42 C151.82,424.12 172.58,365.85 205.33,317.00 C257.37,239.38 349.03,180.93 442.00,166.07 C464.04,162.55 478.67,161.69 505.88,162.29 C555.48,163.38 594.16,171.21 639.00,189.25 C659.38,197.45 694.34,215.75 702.79,222.64 L 705.07 224.50 L 699.18 234.00 C695.94,239.23 690.48,248.11 687.05,253.75 C683.61,259.39 680.44,264.00 679.99,264.00 C679.54,264.00 674.52,261.04 668.84,257.42 C655.11,248.69 625.53,234.22 610.00,228.66 C583.75,219.25 553.35,212.43 527.00,210.05 C512.11,208.70 478.67,208.71 464.00,210.07 C448.87,211.47 421.38,216.98 407.00,221.49 C359.48,236.39 317.14,262.02 281.44,297.50 C258.31,320.48 241.26,343.77 226.14,373.00 C202.42,418.87 191.69,463.62 191.74,516.50 C191.78,555.23 197.10,585.98 210.10,622.48 C215.21,636.83 229.38,665.53 238.40,679.79 C258.58,711.72 284.51,739.87 314.60,762.50 C358.47,795.49 416.85,818.66 475.00,826.15 C490.90,828.19 536.15,827.93 552.00,825.69 C589.08,820.47 619.66,811.35 651.80,795.94 C758.47,744.79 825.34,642.74 828.69,526.00 C830.16,474.91 818.90,425.90 794.39,376.67 C790.88,369.61 788.00,363.68 788.00,363.49 C788.00,362.88 830.91,349.00 832.81,349.00 C834.20,349.00 836.30,352.42 841.26,362.75 C849.43,379.78 850.04,381.23 856.16,398.49 C887.34,486.35 882.15,583.99 841.89,667.00 C819.83,712.49 793.79,746.96 757.00,779.42 C700.79,829.00 634.78,859.47 560.50,870.11 ZM 335.80 648.00 L 331.50 660.50 L 297.25 660.76 C278.41,660.91 263.00,660.77 263.00,660.45 C263.00,659.86 278.07,617.38 291.17,581.00 C295.04,570.28 308.24,533.38 320.52,499.00 C332.80,464.62 347.87,422.55 354.01,405.50 C360.15,388.45 366.62,370.45 368.39,365.50 L 371.61 356.50 L 409.10 356.24 L 446.59 355.98 L 457.22 385.74 C463.07,402.11 475.32,436.42 484.45,462.00 C493.58,487.58 502.36,512.10 503.97,516.50 C505.58,520.90 515.27,547.90 525.51,576.50 C535.75,605.10 546.52,635.12 549.43,643.22 C552.35,651.31 554.49,658.17 554.20,658.47 C553.91,658.76 537.97,659.00 518.78,659.00 L 483.90 659.00 L 482.58 655.75 C481.85,653.96 477.26,640.69 472.38,626.26 L 463.50 600.02 L 352.45 600.00 L 346.28 617.75 C342.88,627.51 338.17,641.12 335.80,648.00 ZM 687.50 661.35 C660.93,665.46 637.94,663.57 615.06,655.41 C601.27,650.49 591.03,644.01 580.37,633.46 C572.36,625.53 570.61,623.14 566.13,613.96 C560.20,601.81 557.14,589.54 556.76,576.32 L 556.50 567.50 L 616.57 566.97 L 617.62 574.74 C620.91,598.97 640.94,614.52 666.50,612.68 C689.18,611.04 704.64,597.72 707.93,576.97 C709.92,564.44 706.02,552.13 697.07,542.67 C687.39,532.43 676.26,529.04 652.23,529.02 L 636.96 529.00 L 637.23 504.75 L 637.50 480.50 L 654.00 479.93 C674.62,479.21 680.48,477.31 690.26,468.16 C697.55,461.34 700.26,455.37 700.77,445.00 C701.35,433.25 698.88,426.59 691.06,418.89 C682.94,410.89 676.70,408.61 663.00,408.61 C649.61,408.61 643.48,410.81 635.00,418.66 C628.14,425.01 625.48,428.98 622.42,437.42 L 620.22 443.50 L 591.93 443.77 C576.36,443.91 563.30,443.69 562.90,443.27 C561.92,442.23 564.65,426.97 567.16,419.51 C578.07,387.00 606.35,365.08 645.92,358.47 C659.23,356.24 682.31,356.90 695.19,359.88 C714.30,364.30 729.13,372.16 741.60,384.49 C755.80,398.54 761.90,412.81 762.75,434.04 C763.17,444.62 762.92,447.89 761.13,455.04 C756.76,472.50 747.16,486.30 733.31,495.04 C729.72,497.32 727.16,499.52 727.64,499.94 C728.11,500.37 731.08,501.76 734.24,503.03 C747.92,508.57 761.40,522.70 767.11,537.47 C771.91,549.87 773.33,559.36 772.69,574.50 C772.04,589.80 770.30,597.27 764.55,609.50 C751.70,636.85 723.57,655.78 687.50,661.35 ZM 370.99 545.75 C371.00,546.73 379.19,547.00 408.61,547.00 C438.28,547.00 446.12,546.74 445.75,545.75 C445.49,545.06 437.02,519.64 426.93,489.25 C416.83,458.86 408.31,434.00 407.99,434.00 C407.33,434.00 370.98,543.79 370.99,545.75 Z" fill="rgb(4,4,4)"/>
+<path d="M 806.90 322.97 C785.45,328.12 765.24,322.48 749.97,307.09 C737.88,294.91 733.00,282.92 733.00,265.40 C733.00,254.57 734.84,247.01 739.72,237.71 C746.39,225.02 759.41,213.62 772.68,208.85 C780.93,205.88 799.11,205.17 807.92,207.47 C830.44,213.34 847.16,231.12 851.67,253.99 C855.45,273.14 849.31,292.70 835.02,307.04 C826.17,315.92 818.73,320.14 806.90,322.97 Z" fill="rgb(248,175,81)"/>
+</g>
+</svg>