cortena-ui 1.4.2 → 1.5.0

package/dist/index.js

@@ -3,22 +3,27 @@ import { cn } from "./lib/cn.js";
 import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "./components/accordion.js";
 import { Alert, AlertDescription, AlertIcon, AlertTitle, alertVariants } from "./components/alert.js";
 import { Avatar, AvatarFallback, AvatarImage } from "./components/avatar.js";
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "./components/dropdown-menu.js";
+import { DEFAULT_THEME_STORAGE_KEY, THEME_MESSAGE_TYPE, applyStoredTheme, applyTheme, getThemeInitScript, readStoredTheme, themeFromBackground, themeFromMessage, themeInitScript, useCortenaTheme } from "./hooks/use-cortena-theme.js";
+import { AppShell, BottomRightCluster, BrandMark, HelpButton, ThemeToggle, documentTitle } from "./components/app-shell.js";
+import { Button, buttonVariants } from "./components/button.js";
+import { Input, inputClassName } from "./components/input.js";
+import { Label, labelVariants } from "./components/label.js";
+import { Spinner } from "./components/spinner.js";
+import { AuthScreen, GoogleMark, LoginScreen, MicrosoftMark, httpsLogoUrl } from "./components/login-screen.js";
 import { Badge, badgeVariants } from "./components/badge.js";
 import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "./components/breadcrumb.js";
-import { Button, buttonVariants } from "./components/button.js";
 import { ButtonLink } from "./components/button-link.js";
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./components/card.js";
 import { Checkbox } from "./components/checkbox.js";
 import { Chip, chipVariants } from "./components/chip.js";
-import { Input, inputClassName } from "./components/input.js";
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxClear, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, useComboboxFilter } from "./components/combobox.js";
 import { Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from "./components/dialog.js";
 import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandLoading, CommandSeparator, CommandShortcut } from "./components/command.js";
-import { DEFAULT_THEME_STORAGE_KEY, THEME_MESSAGE_TYPE, applyStoredTheme, applyTheme, getThemeInitScript, readStoredTheme, themeFromBackground, themeFromMessage, themeInitScript, useCortenaTheme } from "./hooks/use-cortena-theme.js";
-import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "./components/dropdown-menu.js";
+import { ConsentScreen } from "./components/consent-screen.js";
+import { DEFAULT_SESSION_POLICY, SESSION_CHANNEL_NAME, SessionExpiryDialog, SessionGuard, decodeSessionClaims, formatCountdown, useSessionGuard } from "./components/session-guard.js";
 import { EmptyState } from "./components/empty-state.js";
 import { ErrorBanner } from "./components/error-banner.js";
-import { Label, labelVariants } from "./components/label.js";
 import { Field, FieldContent, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, Fieldset, FieldsetLegend, fieldVariants } from "./components/field.js";
 import { Kbd } from "./components/kbd.js";
 import { Skeleton } from "./components/skeleton.js";
@@ -33,7 +38,6 @@ import { Segmented } from "./components/segmented.js";
 import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue } from "./components/select.js";
 import { Separator } from "./components/separator.js";
 import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, sheetVariants } from "./components/sheet.js";
-import { Spinner } from "./components/spinner.js";
 import { StatusDot } from "./components/status-dot.js";
 import { Switch } from "./components/switch.js";
 import { Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger } from "./components/tabs.js";
@@ -47,10 +51,18 @@ import { DatePicker, DateRangePicker, formatDateDefault } from "./components/dat
 import { Dropzone, FileList, formatFileSize } from "./components/dropzone.js";
 import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useForm, useFormField, zodResolver } from "./components/form.js";
 import { downloadCsv, downloadExcel, toCsv, toSheet } from "./components/data-table/export.js";
-import { DataTableColumnHeader, DataTableExportMenu, DataTableFacetedFilter, DataTablePagination, DataTableToolbar, DataTableViewOptions } from "./components/data-table/parts.js";
+import { DataTableColumnHeader, DataTableExportMenu, DataTableFacetedFilter, DataTablePagination, DataTableRefresh, DataTableToolbar, DataTableViewOptions } from "./components/data-table/parts.js";
 import { createColumnHelper, dataTableFeatures } from "./components/data-table/features.js";
 import { useDataTable } from "./components/data-table/use-data-table.js";
 import { DataTable, DataTableView } from "./components/data-table/data-table.js";
+import { ADMIN_ROUTES, ADMIN_ROUTE_LABELS, adminErrorMessage, effectiveRolesOf, sourceGroupOf } from "./components/admin-permissions/types.js";
+import { AdminPermissionsProvider, useAdminPermissions } from "./components/admin-permissions/context.js";
+import { AdminLicenceScreen } from "./components/admin-permissions/licence.js";
+import { AdminMatrix } from "./components/admin-permissions/matrix.js";
+import { DirectRoles, EffectiveRoles, RoleAssignmentDialog } from "./components/admin-permissions/role-assignment.js";
+import { AdminMembers } from "./components/admin-permissions/members.js";
+import { AdminRoles } from "./components/admin-permissions/roles.js";
+import { AdminPermissions } from "./components/admin-permissions/admin-permissions.js";
 import { VIZ_SERIES_COUNT, chartScales, resolveColor, resolveVizSeries, toHex, vizSeriesVars, vizVar } from "./components/chart/tokens.js";
 import { ChartContainer, ChartEmpty, ChartError, ChartLegendContent, ChartLoading, ChartTooltipContent, seriesColor, useChart } from "./components/chart/container.js";
 import { NIVO_TYPES, RECHARTS_TYPES, chartEngine } from "./components/chart/types.js";
@@ -58,9 +70,10 @@ import { Chart } from "./components/chart/chart.js";
 import { ChartLegend, ChartTooltip } from "./components/chart/recharts-parts.js";
 import { Area, AreaChart, Bar, BarChart, CartesianGrid, Cell, ComposedChart, Funnel, FunnelChart, LabelList, Line, LineChart, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Radar, RadarChart, RechartsLegend, RechartsTooltip, ReferenceLine, ResponsiveContainer, Scatter, ScatterChart, XAxis, YAxis } from "./components/chart/index.js";
 import { Markdown, markdownSanitizeSchema } from "./components/markdown.js";
+import { HelpHotkeys, HelpPanel, helpPanelSlot, httpDocumentUrl, parseHelpDocument, resolveHelpTarget, useHelpHotkeys } from "./components/help-panel.js";
 import { A2UIErrorCard } from "./a2ui/views.js";
 import { A2UI_CATALOGUE_ID, catalogueNames, defaultCatalogue } from "./a2ui/catalogue.js";
 import { A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer } from "./a2ui/message.js";
 import { A2UIRenderer } from "./a2ui/renderer.js";
 import { SortableHandle, SortableList, arrayMove } from "./components/sortable-list.js";
-export { A2UIErrorCard, A2UIRenderer, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertIcon, AlertTitle, Area, AreaChart, Avatar, AvatarFallback, AvatarImage, Badge, Bar, BarChart, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonLink, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CartesianGrid, Cell, Chart, ChartContainer, ChartEmpty, ChartError, ChartLegend, ChartLegendContent, ChartLoading, ChartTooltip, ChartTooltipContent, Checkbox, Chip, Combobox, ComboboxChip, ComboboxChips, ComboboxClear, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, DEFAULT_THEME_STORAGE_KEY, DataTable, DataTableColumnHeader, DataTableExportMenu, DataTableFacetedFilter, DataTablePagination, DataTableToolbar, DataTableView, DataTableViewOptions, DateField, DatePicker, DateRangePicker, Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Dropzone, EmptyState, ErrorBanner, Field, FieldContent, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, Fieldset, FieldsetLegend, FileList, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Funnel, FunnelChart, Input, Kbd, Label, LabelList, Line, LineChart, LoadingSkeleton, Markdown, NIVO_TYPES, PageHeader, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, ProgressTrack, ProgressValue, RECHARTS_TYPES, Radar, RadarChart, RadioGroup, RadioGroupItem, RechartsLegend, RechartsTooltip, ReferenceLine, ResponsiveContainer, Scatter, ScatterChart, ScrollArea, ScrollBar, SectionCard, Segmented, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, SortableHandle, SortableList, Spinner, StatusDot, Switch, THEME_MESSAGE_TYPE, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, Toast, Toaster, Toolbar, ToolbarEnd, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, VIZ_SERIES_COUNT, XAxis, YAxis, alertVariants, applyStoredTheme, applyTheme, arrayMove, badgeVariants, buttonVariants, catalogueNames, chartEngine, chartScales, chipVariants, cn, createColumnHelper, dataTableFeatures, defaultCatalogue, downloadCsv, downloadExcel, fieldVariants, foldMessages, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, getAtPointer, getThemeInitScript, inputClassName, isDataBinding, labelVariants, markdownSanitizeSchema, parseA2UIMessages, parseDateDefault, parseDateISO, pointerSegments, readAction, readChildren, readComponent, readStoredTheme, resolveColor, resolvePointer, resolveValue, resolveVizSeries, seriesColor, setAtPointer, sheetVariants, textareaClassName, themeFromBackground, themeFromMessage, themeInitScript, toCsv, toHex, toSheet, toastVariants, useChart, useComboboxFilter, useCortenaTheme, useDataTable, useForm, useFormField, useToast, vizSeriesVars, vizVar, zodResolver };
+export { A2UIErrorCard, A2UIRenderer, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, ADMIN_ROUTES, ADMIN_ROUTE_LABELS, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AdminLicenceScreen, AdminMatrix, AdminMembers, AdminPermissions, AdminPermissionsProvider, AdminRoles, Alert, AlertDescription, AlertIcon, AlertTitle, AppShell, Area, AreaChart, AuthScreen, Avatar, AvatarFallback, AvatarImage, Badge, Bar, BarChart, BottomRightCluster, BrandMark, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonLink, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CartesianGrid, Cell, Chart, ChartContainer, ChartEmpty, ChartError, ChartLegend, ChartLegendContent, ChartLoading, ChartTooltip, ChartTooltipContent, Checkbox, Chip, Combobox, ComboboxChip, ComboboxChips, ComboboxClear, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, ConsentScreen, DEFAULT_SESSION_POLICY, DEFAULT_THEME_STORAGE_KEY, DataTable, DataTableColumnHeader, DataTableExportMenu, DataTableFacetedFilter, DataTablePagination, DataTableRefresh, DataTableToolbar, DataTableView, DataTableViewOptions, DateField, DatePicker, DateRangePicker, Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DirectRoles, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Dropzone, EffectiveRoles, EmptyState, ErrorBanner, Field, FieldContent, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, Fieldset, FieldsetLegend, FileList, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Funnel, FunnelChart, GoogleMark, HelpButton, HelpHotkeys, HelpPanel, Input, Kbd, Label, LabelList, Line, LineChart, LoadingSkeleton, LoginScreen, Markdown, MicrosoftMark, NIVO_TYPES, PageHeader, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, ProgressTrack, ProgressValue, RECHARTS_TYPES, Radar, RadarChart, RadioGroup, RadioGroupItem, RechartsLegend, RechartsTooltip, ReferenceLine, ResponsiveContainer, RoleAssignmentDialog, SESSION_CHANNEL_NAME, Scatter, ScatterChart, ScrollArea, ScrollBar, SectionCard, Segmented, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, SessionExpiryDialog, SessionGuard, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, SortableHandle, SortableList, Spinner, StatusDot, Switch, THEME_MESSAGE_TYPE, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, ThemeToggle, Toast, Toaster, Toolbar, ToolbarEnd, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, VIZ_SERIES_COUNT, XAxis, YAxis, adminErrorMessage, alertVariants, applyStoredTheme, applyTheme, arrayMove, badgeVariants, buttonVariants, catalogueNames, chartEngine, chartScales, chipVariants, cn, createColumnHelper, dataTableFeatures, decodeSessionClaims, defaultCatalogue, documentTitle, downloadCsv, downloadExcel, effectiveRolesOf, fieldVariants, foldMessages, formatCountdown, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, getAtPointer, getThemeInitScript, helpPanelSlot, httpDocumentUrl, httpsLogoUrl, inputClassName, isDataBinding, labelVariants, markdownSanitizeSchema, parseA2UIMessages, parseDateDefault, parseDateISO, parseHelpDocument, pointerSegments, readAction, readChildren, readComponent, readStoredTheme, resolveColor, resolveHelpTarget, resolvePointer, resolveValue, resolveVizSeries, seriesColor, setAtPointer, sheetVariants, sourceGroupOf, textareaClassName, themeFromBackground, themeFromMessage, themeInitScript, toCsv, toHex, toSheet, toastVariants, useAdminPermissions, useChart, useComboboxFilter, useCortenaTheme, useDataTable, useForm, useFormField, useHelpHotkeys, useSessionGuard, useToast, vizSeriesVars, vizVar, zodResolver };

package/dist/markdown.d.ts

@@ -1,3 +1,4 @@
 "use client";
 import { CodeRendererProps, Markdown, MarkdownComponents as Components, MarkdownProps, markdownSanitizeSchema } from "./components/markdown.js";
-export { type CodeRendererProps, Markdown, type Components as MarkdownComponents, type MarkdownProps, markdownSanitizeSchema };
+import { HelpDocument, HelpHotkeys, HelpHotkeysOptions, HelpHotkeysProps, HelpPanel, HelpPanelProps, HelpPanelSlotConfig, HelpRoute, HelpSection, HelpSource, helpPanelSlot, httpDocumentUrl, parseHelpDocument, resolveHelpTarget, useHelpHotkeys } from "./components/help-panel.js";
+export { type CodeRendererProps, type HelpDocument, HelpHotkeys, type HelpHotkeysOptions, type HelpHotkeysProps, HelpPanel, type HelpPanelProps, type HelpPanelSlotConfig, type HelpRoute, type HelpSection, type HelpSource, Markdown, type Components as MarkdownComponents, type MarkdownProps, helpPanelSlot, httpDocumentUrl, markdownSanitizeSchema, parseHelpDocument, resolveHelpTarget, useHelpHotkeys };

package/dist/markdown.js

@@ -1,3 +1,4 @@
 "use client";
 import { Markdown, markdownSanitizeSchema } from "./components/markdown.js";
-export { Markdown, markdownSanitizeSchema };
+import { HelpHotkeys, HelpPanel, helpPanelSlot, httpDocumentUrl, parseHelpDocument, resolveHelpTarget, useHelpHotkeys } from "./components/help-panel.js";
+export { HelpHotkeys, HelpPanel, Markdown, helpPanelSlot, httpDocumentUrl, markdownSanitizeSchema, parseHelpDocument, resolveHelpTarget, useHelpHotkeys };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "cortena-ui",
-  "version": "1.4.2",
-  "description": "Cortena UI — the shared React component library for cortenaweb and every Cortena extension. shadcn over Base UI, styled entirely from cortena-design tokens.",
-  "license": "UNLICENSED",
+  "version": "1.5.0",
+  "description": "Cortena UI \u2014 the shared React component library for cortenaweb and every Cortena extension. shadcn over Base UI, styled entirely from cortena-design tokens.",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AscendendenceAI/cortena-design.git",
@@ -16,6 +16,7 @@
     "node": ">=22"
   },
   "files": [
+    "LICENSE",
     "dist",
     "src",
     "README.md"
@@ -53,6 +54,10 @@
       "types": "./dist/sortable-list.d.ts",
       "default": "./dist/sortable-list.js"
     },
+    "./agent-chat": {
+      "types": "./dist/agent-chat.d.ts",
+      "default": "./dist/agent-chat.js"
+    },
     "./styles.css": "./src/styles/index.css",
     "./package.json": "./package.json"
   },
@@ -69,8 +74,9 @@
     "bundle:probe": "node scripts/bundle-probe.mjs"
   },
   "peerDependencies": {
+    "@ag-ui/client": "^0.0.59",
     "@tanstack/react-query": "^5.0.0",
-    "cortena-design": ">=3.2.0",
+    "cortena-design": ">=3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^3.25.0 || ^4.0.0"
@@ -108,6 +114,7 @@
     "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
+    "@ag-ui/client": "^0.0.59",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-query": "^5.102.8",
     "@types/node": "^22.20.1",
@@ -130,5 +137,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@ag-ui/client": {
+      "optional": true
+    }
   }
 }

package/src/agent-chat/a2ui-block.ts

@@ -0,0 +1,118 @@
+/**
+ * A2UI blocks as the chat carries them.
+ *
+ * Ported from `cortena-shared/src/a2ui/block.ts` (Cortena monorepo, DESIGN-35).
+ * `cortena-shared` is not published, so the parts this package needs are copied
+ * rather than imported; keep the two in step when either changes.
+ *
+ * An agent draws UI by writing a ```a2ui fenced block, cortenacore strips it out
+ * of the prose, and it reaches the client on a channel of its own — a
+ * `CUSTOM cortena.a2ui` event on the AG-UI transport. Both the streaming bubble
+ * and the finished message carry the result here, so the bubble has exactly one
+ * thing to render and no markdown to parse.
+ *
+ * Nothing in this module knows about React: the `messages` array is handed to
+ * `<A2UIRenderer message={...} />` verbatim, and folding a surface, validating a
+ * component and drawing it are the renderer's job.
+ */
+
+/** One block, as the transport delivers it. */
+export interface A2UIChatBlock {
+  /**
+   * Accumulation key: the surface id the payload names, or a key private to the
+   * block when it names none. Two blocks with the same key are two pushes to one
+   * surface and fold together.
+   */
+  surfaceId: string;
+  /** A2UI messages, in arrival order. */
+  messages: unknown[];
+  /** Where the block came from: assistant text, or a `canvas` tool push. */
+  source?: "text" | "canvas";
+  /** Assistant message the block belonged to, when the transport knows it. */
+  messageId?: string;
+  /** Set when the fence never closed or its body did not parse. */
+  error?: string;
+  /** The raw fence body; only present with `error`. */
+  raw?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read one block out of an unknown wire value; `null` when it is not one. */
+export function readA2UIBlock(value: unknown): A2UIChatBlock | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const messages = Array.isArray(value.messages) ? value.messages : [];
+  const surfaceId =
+    typeof value.surfaceId === "string" && value.surfaceId ? value.surfaceId : "@default";
+  const error = typeof value.error === "string" && value.error ? value.error : undefined;
+  if (messages.length === 0 && !error) {
+    return null;
+  }
+  return {
+    surfaceId,
+    messages,
+    ...(value.source === "canvas" || value.source === "text" ? { source: value.source } : {}),
+    ...(typeof value.messageId === "string" && value.messageId
+      ? { messageId: value.messageId }
+      : {}),
+    ...(error ? { error } : {}),
+    ...(typeof value.raw === "string" ? { raw: value.raw } : {}),
+  };
+}
+
+/**
+ * Pull the `a2ui` content parts out of a chat event message.
+ *
+ * A client that does not know the type ignores it, which is what lets the same
+ * message shape carry blocks to a reader that cannot draw them.
+ */
+export function extractA2UIBlocks(
+  message?: { content?: Array<Record<string, unknown>> } | null,
+): A2UIChatBlock[] {
+  const blocks: A2UIChatBlock[] = [];
+  for (const part of message?.content ?? []) {
+    if (!isRecord(part) || part.type !== "a2ui") {
+      continue;
+    }
+    const block = readA2UIBlock(part.a2ui ?? part);
+    if (block) {
+      blocks.push(block);
+    }
+  }
+  return foldA2UIBlocks(blocks);
+}
+
+/**
+ * Fold blocks that share a surface id into one, concatenating their messages.
+ *
+ * An agent that streams a surface writes the shell, then the rows, then a
+ * correction — three fences naming one surface. The renderer folds a message
+ * list onto a surface, so handing it the concatenation renders the finished
+ * surface; handing it three separate blocks would draw the shell three times.
+ */
+export function foldA2UIBlocks(blocks: readonly A2UIChatBlock[]): A2UIChatBlock[] {
+  const byId = new Map<string, A2UIChatBlock>();
+  const order: string[] = [];
+  for (const block of blocks) {
+    const existing = byId.get(block.surfaceId);
+    if (!existing) {
+      byId.set(block.surfaceId, { ...block, messages: [...block.messages] });
+      order.push(block.surfaceId);
+      continue;
+    }
+    existing.messages.push(...block.messages);
+    // The first failure is the one worth showing: later ones are usually the
+    // same malformed payload arriving again.
+    if (block.error && !existing.error) {
+      existing.error = block.error;
+      if (block.raw !== undefined) {
+        existing.raw = block.raw;
+      }
+    }
+  }
+  return order.map((id) => byId.get(id)!).filter(Boolean);
+}