@calliopelabs/ui 0.14.0 → 0.18.0

package/README.md

@@ -16,7 +16,7 @@ It is built Storybook first: every component and every screen pattern is built a
 npm i @calliopelabs/ui
 ```
 
-Peer dependencies: `react` and `react-dom` 19, and `tailwindcss` 4 for styling.
+Peer dependencies: `react` and `react-dom` 19, and `tailwindcss` 4 for styling. The opt-in agent entries add `@ag-ui/client` and `@copilotkit/react-core` (see [Agent](#agent)).
 
 ## Styles
 
@@ -428,6 +428,240 @@ const chat = useAgUiRun();
 
 `agent` above is the host's own client. The catalog's `Chat/ChatPanel` composes the pieces the same way, driven by a recorded run. Their copy is in the `chat` message group.
 
+## Agent
+
+`CalliopeAgent` is the one embedded agent for every Calliope AI product: a floating bubble, the shell's right rail, inline in a page, or a page of its own. It speaks [AG-UI](https://docs.ag-ui.com) to any agent, directly or through a [CopilotKit](https://docs.copilotkit.ai) runtime, and draws every pixel with the chat kit above, on the product's tokens, mark and runtime brand. CopilotKit wires the runtime and runs the agent; its UI and stylesheet are never loaded.
+
+It is an opt-in entry, so apps without an agent never load its dependencies:
+
+```sh
+npm i @ag-ui/client                      # @calliopelabs/ui/agent
+npm i @ag-ui/client @copilotkit/react-core   # @calliopelabs/ui/agent/copilotkit (1.79.1 or later, 1.x)
+```
+
+Both are optional peers. `npm run pack:check` fails if the main entry ever reaches them. Most of the entry's weight is `@ag-ui/client` itself (with its protobuf codec, about 150 KB gzipped; the agent's own code is about 24 KB minified), which a CopilotKit app already ships. To keep it off a page's first load, load the provider when the person first opens the assistant (`next/dynamic` with `ssr: false`) and keep it mounted after.
+
+### A Next.js app with a CopilotKit runtime
+
+```ts
+// app/api/copilotkit/route.ts: the runtime, on the server (agents, keys and auth stay here)
+import { HttpAgent } from "@ag-ui/client";
+import { CopilotRuntime, createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
+
+const runtime = new CopilotRuntime({
+  agents: { default: new HttpAgent({ url: process.env.AGENT_URL! }) },
+});
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+  mode: "single-route",
+});
+export const POST = (request: Request) => handler(request);
+```
+
+```tsx
+// app/assistant.tsx
+"use client";
+import { CalliopeAgent, useAgentReadable, useAgentTool } from "@calliopelabs/ui/agent";
+import { CopilotKitAgentProvider } from "@calliopelabs/ui/agent/copilotkit";
+import { z } from "zod";
+
+export function Assistant({ children, project }: { children: React.ReactNode; project: string }) {
+  return (
+    <CopilotKitAgentProvider
+      runtimeUrl="/api/copilotkit"
+      useSingleEndpoint
+      headers={{ "x-project": project }}
+    >
+      {children}
+      <CalliopeAgent mode="bubble" persistKey="app.assistant.open" />
+    </CopilotKitAgentProvider>
+  );
+}
+
+// Anywhere under it, while mounted:
+useAgentReadable("The open project", { project });
+useAgentTool({
+  name: "open_scene",
+  parameters: z.object({ id: z.string() }),
+  handler: ({ id }) => router.push(`/scenes/${id}`),
+});
+```
+
+Mount it from the root layout (a Server Component) as `<Assistant project={slug}>{children}</Assistant>`. Tools carry functions, so they are registered in client components, never passed from a server one.
+
+### A plain AG-UI endpoint
+
+```tsx
+"use client";
+import { CalliopeAgent, CalliopeAgentProvider } from "@calliopelabs/ui/agent";
+
+<CalliopeAgentProvider url="/api/agui" headers={{ "x-project": slug }} suggestions={startingPoints}>
+  <AppShell
+    {...shell}
+    rightRail={<CalliopeAgent mode="rail" open={open} onOpenChange={setOpen} />}
+    rightRailLabel="Assistant"
+    onToggleRightRail={() => setOpen((o) => !o)}
+  >
+    {children}
+  </AppShell>
+</CalliopeAgentProvider>;
+```
+
+`url` makes an `HttpAgent` (same origin, so the session cookie goes along); `agent` takes any `AbstractAgent` instead. `createFunctionAgent(run)` turns a function that yields AG-UI events (or an existing non-AG-UI endpoint, adapted) into one.
+
+### What it does
+
+- **One conversation, one store.** `useCalliopeAgent()` returns the chat kit's `ChatView` (messages, tool calls, steps, interrupts, shared state, custom events) and the actions: `send(text, { parts })`, `stop()` (aborts the run and any tool waiting), `regenerate()`, `approve(call)` and `deny(call, reason)`, `resolveInterrupt(id, response)`, `respond(toolCallId, result)`, `getState()` and `setState(state)`, `switchThread(id)` (with the provider's `loadThread`) and `newThread()`, plus `running`, `waiting`, `unread` and `suggestions`.
+- **Tools.** `useAgentTool(defineTool({ name, description, parameters, handler, render, followUp }))` offers a browser tool while the component is mounted. `parameters` is a Standard Schema (zod 4, valibot, arktype), which types and validates the arguments, or a JSON Schema. A tool with `render` and no `handler` is human-in-the-loop: the run waits until its card calls `respond(result)`, and the composer holds meanwhile.
+- **Readables and suggestions.** `useAgentReadable(description, value)` sends page context with every run; `useAgentSuggestions([{ title, message }])` offers starting points. Both also come as provider props for the whole app.
+- **Approvals.** A run that ends on an AG-UI interrupt pauses. A tool call it names gets approve and deny on its card (a denial always with a reason); any other interrupt gets `InterruptCard`, or the host's `renderers.interrupts[reason]`. The run resumes with AG-UI `resume` once every open interrupt has an answer; a new message cancels what is still open.
+- **Generative UI.** `renderers` on `CalliopeAgent` maps tool names (backend tools too), `CUSTOM` event names and interrupt reasons to host components, and draws the shared state above the conversation. `workflowRenderers` draws the run and review components: `calliope.run` on `RunTimeline` (events with one `id` update one card), `calliope.artifact` on `ArtifactCard` with `DocumentReview`, `MediaReview` or `FormReview` (signing or sending the review resumes the run), and `calliope.question` interrupts on `WorkflowQuestionCard`.
+- **Surfaces.** `mode="bubble"` (a launcher and a non-modal panel; a drawer on phones), `"rail"` (a `RailPanel` for `AppShell`'s `rightRail`; the shell's drawer on phones), `"inline"` and `"page"`. Open state is controlled, held, or remembered per person with `persistKey`; `shortcut` (`mod+/` by default) toggles it; answers that land while it is closed show as unread on the launcher. Slots: `renderContent` (the host's markdown), `attachments` and `sendOptions` (attachments as AG-UI input parts), `composerActions`, `modelPicker` (pass the choice in the provider's `forwardedProps`), `headerActions`, `empty`.
+- **Telemetry and errors.** `onEvent(event)` sees every AG-UI event; `onError(error)` every failed run (also shown in the conversation with retry).
+- **Testing.** `createMockAgent({ turns })` plays recorded turns; `createFunctionAgent(run)` makes an agent of any function that yields AG-UI events. Both are real `HttpAgent`s answered in the page, so stories and tests need no network.
+
+Headers on the provider run in the browser: never put a secret there. Keys, the model and authorization stay on the server, in the runtime route or the agent. Copy is in the `agent` message group.
+
+### Moving to it
+
+| Product                              | Today                                                                                                                                                                           | With `CalliopeAgent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Astrolift Studio                     | `CopilotKitProvider` (1.79.1) and its own `AssistantPanel`, `AssistantTranscript`, `AssistantInput`, `SuggestionChips`, `AssistantLauncher`, `dock.tsx`, `useStored` open state | `CopilotKitAgentProvider runtimeUrl="/api/assistant" useSingleEndpoint agentId="studio" headers={{ [PROJECT_HEADER]: slug }}` (or keep its `CopilotKitProvider`: ours reuses it) and `<CalliopeAgent mode="rail" persistKey={openKey}>` in the shell's rail. The 15 `useHumanInTheLoop` actions become `useAgentTool({ name, parameters, render })` with `ActionCard` as `render` (calling `respond`); the whiteboard tools become `useAgentTool` with their zod schemas; `useAgentContext` readables become `useAgentReadable`; `startingPoints` becomes `useAgentSuggestions`; thread loading becomes `loadThread`. The server route and runner stay. |
+| Zentinelle                           | `ChatBubble` (sparkle button, `Drawer`), `use-chat` parsing a custom `data:` stream, `MessageList`, `ChatInput`, `ModelSelector`, full-page `AssistantScreen`                   | `<CalliopeAgent mode="bubble">` and `mode="page"`, with `modelPicker` fed from `/assistant/providers` and the model in `forwardedProps`. Transport: port `/assistant/chat` to AG-UI (`pending_action` as an interrupt, `navigation` as a `CUSTOM` event drawn as a link chip), or until then adapt it with `createFunctionAgent` over `authenticatedFetch`. An approval resolves the interrupt; the host's `execute-tool` call with the approval token stays a host action in the interrupt renderer, gated on `canMutate`.                                                                                                                             |
+| Astrolift app (Wayfinding)           | `WayfindingBubble` and `use-wayfinding` posting to `/wayfinding/ask/`                                                                                                           | `<CalliopeAgent mode="bubble">` over `createFunctionAgent` that posts the question and returns the answer as text and the routes as a `CUSTOM` event, drawn by a `renderers.custom.routes` component of `Link` chips that close the panel. No tools: read-only by construction. A 503 thrown from the function shows as the run's error.                                                                                                                                                                                                                                                                                                                |
+| Boilerworks django-nextjs-copilotkit | CopilotKit 1.63.1 v1 (`CopilotKit`, `CopilotSidebar`, `useCopilotAction`, `useCopilotReadable`, `react-ui` CSS re-themed)                                                       | Upgrade to `@copilotkit/react-core` 1.79+ and `@copilotkit/runtime/v2` (the runtime route keeps its `HttpAgent` to Django), then `CopilotKitAgentProvider runtimeUrl="/api/copilotkit" agentId="boilerworks_agent"` and `<CalliopeAgent mode="rail">` in place of `CopilotSidebar`. `useCopilotReadable` becomes `useAgentReadable`; `renderAndWaitForResponse` becomes `useAgentTool` with `render` and `respond`; the render-only `draft_form_definition` card becomes `renderers.tools.draft_form_definition`. Drop `@copilotkit/react-ui` and `copilot.css`.                                                                                        |
+
+## Workbench
+
+`@calliopelabs/ui/workbench` is an opt-in entry for IDE-style tools (File Manager, Loadr, Chat Studio): an app without one never loads it. Its styles come from the preset. The code editors and the chart need optional peers the host installs and loads itself (`monaco-editor` through `configureMonaco`, `recharts` through `DataChart`'s `loadCharts`), so the entry builds without either. Like the rest, it is host-driven: data comes in as props, every change goes out through a callback, and nothing fetches.
+
+**New in 0.17.0** (calliopeai/calliope-ux#12, extracted from Loadr and serving Chat Studio's fork too): the IDE shell (`WorkbenchShell`, `MenuBar`, `ActivityBar`, `EditorTabs` and `EditorGroup`, `PaneGroup`, `BottomPanel`, `StatusBar`, `CommandPalette`, `useShortcuts`; #79), the `Menubar` primitive in the main entry (#79), `DataGrid` with editing and pending changes, `DataProfile` and `DataChart` (#81), and `CodeEditor` and `SqlEditor` on Monaco (#80). New dependency: `@tanstack/react-virtual`. New optional peers: `monaco-editor`, `recharts`. Nothing existing changed. The file browser, upload dropzone and preview shipped in 0.16.0.
+
+- **`FileBrowser`**: breadcrumb (its crumbs are drop targets), list and grid views, sorting (folders first, natural order), selection, a context menu, drag-and-drop moves (Alt copies) and an optional folder tree. View, sort and selection work uncontrolled or controlled. Copy for an empty folder, a toolbar slot, and thumbnails for grid tiles.
+- **`FileTree`**: a lazy tree on the WAI-ARIA tree pattern (arrows open and move, Home, End, typeahead). The host answers `onLoad(path)` with a `FileBranch` (`loading`, `error`, `ready`) per directory in `branches`; a failed branch retries through `onRetry`.
+- **`FileList`** and **`FileGrid`**, the two views on their own: a grid (WAI-ARIA grid pattern: arrows between cells, selection follows focus, Shift extends, Cmd/Ctrl moves without selecting, Cmd/Ctrl+A, Escape, Enter opens, Delete, F2 renames) and a multi-select listbox of tiles with two-dimensional arrows.
+- **`UploadDropzone`**: wraps an area (an overlay while desktop files hover, progress floating in a corner) or draws its own box with a picker. `accept` and `maxSize` filter into `onFiles` and `onReject`; the host's `uploads` (`queued`, `uploading` with a percentage or none, `done`, `error`, `canceled`) draw as progress bars with cancel and dismiss.
+- **`FilePreview`**: CSV and TSV (parsed here, quoted fields included) and server-parsed tables in the library's `DataTable` with search, sort and paging; JSON pretty-printed; images; text; markdown through the host's `renderMarkdown` (the package ships no markdown parser, so without one the source shows); a binary fallback, loading, error and a truncation note.
+- Helpers: `FileItem`, `sortFiles`, `previewKindFor`, `parseDelimited`, `formatBytes`, `canDrop`, `pathSegments`, `parentPath`, `joinPath`, `FileIcon`.
+
+```tsx
+import {
+  FileBrowser,
+  FilePreview,
+  UploadDropzone,
+  previewKindFor,
+} from "@calliopelabs/ui/workbench";
+
+<UploadDropzone onFiles={(files) => upload(files, path)} uploads={uploads} onCancel={cancel}>
+  <FileBrowser
+    path={path}
+    items={listing.data?.entries.map(toFileItem)}
+    error={listing.error}
+    onRetry={listing.refetch}
+    onNavigate={setPath}
+    onOpen={(item) => setPreview(item.path)}
+    onMove={(sources, target, { copy }) => (copy ? copyTo : moveTo)(sources, target)}
+    onDelete={confirmDelete}
+    contextMenu={(targets) => <FileActions targets={targets} />}
+    tree={{ root, branches, onLoad: loadFolder, onRetry: loadFolder }}
+  />
+</UploadDropzone>;
+```
+
+Their copy is in the `workbench` message group. The catalog's **Workbench** section shows every state, light and dark, narrow, and large trees.
+
+### The IDE shell
+
+Extracted from Loadr's layout (shared with Chat Studio). Every region is host content and every toggle a prop; the shell holds no state but the pane sizes.
+
+- **`WorkbenchShell`**: menu bar, activity bar, a resizable side bar, the editors over a bottom panel, an optional right-hand panel, and the status bar. Hidden regions stay mounted, so an open page keeps its state; a maximized panel collapses the editors without unmounting them. `storageKey` remembers pane sizes per person.
+- **`MenuBar`**: menus from data (`WorkbenchMenu`: items with shortcuts, checkbox items, labels, separators) on the `Menubar` primitive (WAI-ARIA menubar). `start` and `end` slots for the product mark and name.
+- **`ActivityBar`**: the rail of views as a vertical toolbar of toggle buttons (one tab stop, arrows move), with labels, badges, footer items, and items that toggle a panel instead of choosing a view. Choosing the open view passes `null`, so the host closes the side bar.
+- **`EditorTabs`** and **`EditorGroup`**: the WAI-ARIA tabs pattern with an unsaved marker (spoken), close by button, middle click or Delete, reorder by drag or Alt+Shift+Left/Right, a menu of every tab once the strip overflows, a per-tab context menu, trailing actions and a focused-group marker for split layouts. `EditorGroup` adds the labelled tab panel.
+- **`PaneGroup`** and **`Pane`**: resizable panes on the WAI-ARIA window-splitter pattern (focusable `separator`s; arrows step, Home and End go to the bounds; pointer drag). Bounds in percent or pixels, collapsed panes stay mounted, sizes persist through `storageKey` (the library's local store).
+- **`BottomPanel`**: views as tabs with counts, maximize, restore and close.
+- **`StatusBar`** and **`StatusBarItem`**: a labelled region with start and end slots; `tone` paints it with a status colour (a production connection in `error`).
+- **`CommandPalette`**: a modal WAI-ARIA combobox over a grouped listbox with fuzzy ranking (`fuzzyScore`, `rankItems`), recent entries, key caps, a loading state, controlled query for prefix modes ("@" for objects), and `onItemKeyDown` for host keys on the highlighted entry. Focus returns where it was.
+- **`useShortcuts`**, **`KeyboardShortcutsDialog`**, **`ShortcutKeys`**: a page-wide registry with one listener; chords are strings (`"Mod+K"`: Command on a Mac, Control elsewhere); bare keys stay out of text fields; the last mounted binding wins; the dialog lists whatever is registered. `parseShortcut`, `matchesShortcut`, `formatShortcut` are pure.
+
+```tsx
+useShortcuts([
+  { id: "palette", keys: "Mod+K", label: "Command palette", run: () => setPalette(true) },
+  { id: "sidebar", keys: "Mod+B", label: "Toggle side bar", run: toggleSidebar },
+]);
+
+<WorkbenchShell
+  storageKey="loadr"
+  menuBar={<MenuBar menus={menus} end="Loadr" />}
+  activityBar={<ActivityBar items={views} active={view} onActiveChange={setView} />}
+  sidebar={<Explorer />}
+  sidebarOpen={view !== null}
+  bottomPanel={<BottomPanel views={panels} maximized={max} onMaximizedChange={setMax} />}
+  bottomPanelOpen={panelOpen}
+  bottomPanelMaximized={max}
+  statusBar={<StatusBar tone={envTone} start={connection} end={version} />}
+  overlays={
+    <CommandPalette open={palette} onOpenChange={setPalette} items={commands} onSelect={run} />
+  }
+>
+  <EditorGroup tabs={tabs} activeId={active} onSelect={setActive} onClose={close} onReorder={move}>
+    <ActivePage />
+  </EditorGroup>
+</WorkbenchShell>;
+```
+
+### Code and SQL editors
+
+`CodeEditor` wraps Monaco once; `SqlEditor` adds schema-aware completion. Monaco is an optional peer dependency (`monaco-editor` `>=0.52 <1`) that the package never imports: the host hands over its own import, so its bundler resolves Monaco, puts it in its own chunk and fetches it the first time an editor mounts. An app without an editor never loads it; without a loader (or if it fails) a plain text area stands in.
+
+```ts
+// Once, at startup (Vite shown; the worker setup is the bundler's part).
+import { configureMonaco } from "@calliopelabs/ui/workbench";
+
+configureMonaco({
+  load: async () => {
+    const [monaco, worker] = await Promise.all([
+      import("monaco-editor"),
+      import("monaco-editor/editor/editor.worker?worker"),
+    ]);
+    self.MonacoEnvironment = { getWorker: () => new worker.default() };
+    return monaco;
+  },
+});
+```
+
+- **`CodeEditor`**: `value`, `onChange`, `language`, `label` (its accessible name), `readOnly`, `onRun` (Ctrl or Command with Enter, the selection or the whole buffer), `options` (Monaco's own), `onMount(editor, monaco)` with an optional cleanup, and a per-editor `loader`. Host value changes are applied as edits, so undo still works. The theme comes from the library's tokens under the editor (ground, text, accent, border; syntax from the chart series) and follows a change of ground or mode; Monaco themes are page-wide.
+- **`SqlEditor`**: a `schema` (`tables` with optional `columns`, `schemas`, `databases`, `otherDatabases`) drives completion: tables after FROM and JOIN, columns after SELECT and WHERE (qualified when two tables share a name), `alias.` resolved against the statement under the cursor, `schema.` and `db.` qualifiers, keywords, functions and window-function snippets. Completion never waits: what the schema lacks (a table's columns, another database's tables) comes out once through `onSchemaRequest`, and the host passes a new `schema`.
+- Pure helpers for anything else: `sqlCompletions(text, offset, schema)`, `sqlCursorContext`, `statementAt`, `extractTableRefs`, `resolveSqlDot`, `isDdlStatement` (a host's cue to refresh its schema), `editorTheme`, `readEditorPalette`.
+
+### Data grid, profile and chart
+
+Extracted from Loadr's result grid and data editor (Chat Studio runs a fork of the same files). Host-driven: rows in, changes and copies out through callbacks, nothing fetches, no toasts.
+
+- **`DataGrid`**: `columns` (names, or `GridColumn` with `type` in any driver spelling, `primaryKey`, `foreignKey`, `nullable`; undeclared types are sniffed) and `rows`. Rows and columns are virtualized (`@tanstack/react-virtual`), so 50,000 rows by 30 columns is a few hundred nodes. The WAI-ARIA grid pattern: arrows, Home and End, Ctrl+Home and Ctrl+End, Page Up and Down, Shift extends, Ctrl or Command with A selects all, with C copies TSV (Shift adds headers); Enter opens the cell, Shift+Enter the row. Cell, row and column selection (Shift and Ctrl or Command with the mouse), sort with NULLs last, a filter, hidden columns, resize by pointer or keyboard (a focusable `separator`; widths persist under `storageKey` in the library's local store), selection statistics, copy as TSV, CSV, JSON, INSERT or Markdown, and export as CSV, TSV, JSON, JSON Lines, SQL INSERT or Markdown. `totalRows` or `hasMore` shows the truncation banner; `loading`, `error` and `onRetry` the states. `onCopy` hears every copy; `onExport` takes over export (each request carries the library's `file` for its formats, `null` for the host's own `exportFormats`, such as a workbook), and `downloadExport(file)` saves one.
+- **Editing**: `editable` turns on in-place editing (Enter, F2, double click or typing; Enter and Tab keep and move, Escape cancels), add, duplicate and delete rows, and a `PendingChangesBar` with Commit and Discard. Existing rows change only when a column is a `primaryKey`; without one, rows can be added. Commit calls `onCommit(changeSet)`: inserts with the filled cells, updates keyed on the primary key with the changed cells and their old values (for an optimistic-concurrency check), deletes by key. Resolve and the grid clears the changes; reject with `{ message, key }` and they stay, with the failed row marked. `pending` and `onPendingChange` control the changes from outside. The model is pure (`editCell`, `addRow`, `deleteRows`, `revertRow`, `pendingCounts`, `toChangeSet`), and `changeSetToSql(changeSet, { table })` writes the statements for a host that runs SQL.
+- **`DataProfile`**: a card per column (completeness, distinct, range, mean and median, top values), sampling at most `rowCap` rows (10,000) and saying so.
+- **`DataChart`**: bar, line, area, scatter or pie of an X column and Y columns, in the theme's chart series. Recharts is an optional peer (`recharts` `^3`) that the package never imports: the host passes `loadCharts={() => import("recharts")}`, so an app without charts builds without it and one with them loads it when a chart opens. Plots at most `rowCap` rows (500).
+- Also exported: `CellDetailDialog`, `RowDetailDrawer`, `TruncationBanner`, `GridCellValue`, `ColumnTypeIcon`, and the pure helpers (`viewRowIndexes`, `compareCells`, `normalizeColumnType`, `buildColumnMeta`, the selection model, `formatMatrix`, `exportMatrix`, `toTSV`, `toCSV`, `toInsert`, `toMarkdown`, `computeStats`, `profileColumn`).
+
+```tsx
+<DataGrid
+  label="public.people"
+  columns={[{ name: "id", type: "int8", primaryKey: true }, "name", "email"]}
+  rows={result.rows}
+  totalRows={result.rowCount}
+  storageKey="table:public.people"
+  tableName="public.people"
+  editable={editMode}
+  onCommit={(changes) => api.apply({ table: "public.people", ...changes })}
+  onExport={(request) =>
+    request.file ? downloadExport(request.file) : writeWorkbook(request.matrix)
+  }
+  exportFormats={[{ id: "xlsx", label: "Excel workbook" }]}
+/>
+```
+
 ## Appearance
 
 The person sets four axes, per product: the **ground** (black, charcoal, graphite, emerald, navy, paper, mist; it decides light or dark), the **accent** (the product's own, a family accent, or any colour that stands 3:1 off the ground), the **density** (`compact` hairline rows or boxed `cards`) and the **corners** (0, 2, 4 or 10 px). `AppearancePicker` is the settings UI for all four.

package/dist/agent/AgentChat.d.ts

@@ -3,6 +3,7 @@ import type { ChatContentRenderer } from "../chat/MessageBubble.js";
 import { type ChatToolCall } from "../chat/model.js";
 import { type ModelPickerProps } from "../chat/ModelPicker.js";
 import type { SendOptions } from "./controller.js";
+import { type AgentRenderers } from "./renderers.js";
 export interface AgentChatProps {
     /** The panel's title. Defaults to the product's assistant ("Astrolift AI assistant"). */
     title?: string;
@@ -23,6 +24,12 @@ export interface AgentChatProps {
     renderToolCall?: (call: ChatToolCall) => React.ReactNode;
     /** The tool's name for people, per call. */
     toolTitle?: (call: ChatToolCall) => string | undefined;
+    /**
+     * Generative UI: host components for tool calls, custom events, interrupts
+     * and the shared state (see `AgentRenderers`; `workflowRenderers` draws the
+     * run and review components). `renderToolCall` still wins for a call.
+     */
+    renderers?: AgentRenderers;
     /** "line": a one-line status while running (bubble, rail). "steps": the run's steps on the run timeline (page). */
     progress?: "line" | "steps" | "none";
     /** Replaces the empty state (the suggestions still show under it). */
@@ -53,4 +60,4 @@ export declare function NewConversationButton({ className }: {
  * their own calls; one that waits on the person gets `respond`, and the
  * composer holds until it is answered.
  */
-export declare function AgentChat({ title, hideHeader, headerActions, onClose, expanded, onExpandedChange, hideNewConversation, renderContent, renderToolCall, toolTitle, progress, empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun, className, }: AgentChatProps): React.JSX.Element;
+export declare function AgentChat({ title, hideHeader, headerActions, onClose, expanded, onExpandedChange, hideNewConversation, renderContent, renderToolCall, toolTitle, renderers, progress, empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun, className, }: AgentChatProps): React.JSX.Element;

package/dist/agent/AgentChat.js

@@ -14,6 +14,8 @@ import { useUI } from "../provider/UIProvider.js";
 import { EmptyState } from "../states/EmptyState.js";
 import { StatusDot } from "../status/StatusDot.js";
 import { useCalliopeAgent } from "./AgentProvider.js";
+import { parseResult } from "./renderers.js";
+import { InterruptCard } from "./WorkflowRenderers.js";
 function ToolRender({ tool, call, waiting, respond, }) {
     return (_jsx(_Fragment, { children: tool.render?.({
             call,
@@ -43,7 +45,7 @@ function Suggestions({ suggestions, disabled, onPick, }) {
  * their own calls; one that waits on the person gets `respond`, and the
  * composer holds until it is answered.
  */
-export function AgentChat({ title, hideHeader = false, headerActions, onClose, expanded, onExpandedChange, hideNewConversation = false, renderContent, renderToolCall, toolTitle, progress = "line", empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun = false, className, }) {
+export function AgentChat({ title, hideHeader = false, headerActions, onClose, expanded, onExpandedChange, hideNewConversation = false, renderContent, renderToolCall, toolTitle, renderers, progress = "line", empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun = false, className, }) {
     const agent = useCalliopeAgent();
     const { messages } = useUI();
     const product = useProduct();
@@ -64,13 +66,52 @@ export function AgentChat({ title, hideHeader = false, headerActions, onClose, e
         const custom = renderToolCall?.(call);
         if (custom !== undefined)
             return custom;
+        const Renderer = renderers?.tools?.[call.name];
+        if (Renderer) {
+            return (_jsx(Renderer, { call: call, args: parseToolCallArgs(call.args), result: parseResult(call), agent: agent, ...(waiting.includes(call.id)
+                    ? { respond: (result) => agent.respond(call.id, result) }
+                    : {}) }));
+        }
         const tool = tools.find((t) => t.name === call.name && t.render);
         if (!tool)
             return undefined;
         return (_jsx(ToolRender, { tool: tool, call: call, waiting: waiting.includes(call.id), respond: agent.respond }));
     };
+    // Custom events, each after the timeline item it arrived after (the first, when before any).
+    const first = view.timeline[0];
+    const firstKey = first ? `${first.kind}:${first.id}` : null;
+    const drawAfter = (item) => {
+        const key = `${item.kind}:${item.id}`;
+        const here = agent.custom.filter((c) => renderers?.custom?.[c.name] && (c.after ?? firstKey) === key);
+        if (here.length === 0)
+            return null;
+        return here.map((c) => {
+            const Renderer = renderers.custom[c.name];
+            return (_jsx("div", { "data-slot": "agent-custom", className: "min-w-0", children: _jsx(Renderer, { name: c.name, value: c.value, history: c.history, agent: agent }) }, c.key));
+        });
+    };
+    // Interrupts that no tool card or artifact answers: drawn after the conversation.
+    const claimed = new Set(agent.custom.flatMap((c) => {
+        const id = c.value?.interruptId;
+        return renderers?.custom?.[c.name] && typeof id === "string" ? [id] : [];
+    }));
+    const loose = view.status === "interrupted"
+        ? view.interrupts.filter((i) => !i.toolCallId && !claimed.has(i.id))
+        : [];
+    const footer = loose.length > 0
+        ? loose.map((interrupt) => {
+            const Renderer = renderers?.interrupts?.[interrupt.reason] ?? InterruptCard;
+            return (_jsx(Renderer, { interrupt: interrupt, agent: agent, resolve: (payload) => agent.resolveInterrupt(interrupt.id, {
+                    status: "resolved",
+                    ...(payload === undefined ? {} : { payload }),
+                }), cancel: () => agent.resolveInterrupt(interrupt.id, { status: "cancelled" }) }, interrupt.id));
+        })
+        : undefined;
+    const StateView = renderers?.state;
     const step = [...view.steps].reverse().find((s) => s.status === "running");
-    return (_jsxs("section", { ref: root, "aria-labelledby": hideHeader ? undefined : headingId, "aria-label": hideHeader ? name : undefined, "data-slot": "agent-chat", className: cn("flex min-h-0 min-w-0 flex-col bg-card text-card-foreground", className), children: [!hideHeader && (_jsxs("div", { className: "flex min-w-0 items-center gap-1 border-b px-3 py-2", children: [_jsx("h2", { id: headingId, className: "min-w-0 flex-1 truncate text-sm font-semibold", children: name }), headerActions, !hideNewConversation && _jsx(NewConversationButton, {}), onExpandedChange && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": expanded ? t.restore : t.expand, title: expanded ? t.restore : t.expand, onClick: () => onExpandedChange(!expanded), children: expanded ? _jsx(Minimize2Icon, { "aria-hidden": true }) : _jsx(Maximize2Icon, { "aria-hidden": true }) })), onClose && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": t.close, title: t.close, onClick: onClose, children: _jsx(XIcon, { "aria-hidden": true }) }))] })), progress === "steps" && view.steps.length > 0 && (_jsx(AgentProgress, { view: view, className: "border-b px-3 py-2" })), _jsx(MessageList, { view: view, renderContent: renderContent, renderToolCall: drawCall, toolTitle: toolTitle, onApprove: (call) => agent.approve(call), onDeny: (call, reason) => agent.deny(call, reason), onRetry: () => void agent.regenerate(), empty: _jsxs("div", { className: "flex flex-col items-center gap-4 py-6", children: [empty ?? _jsx(EmptyState, { title: t.emptyTitle, description: t.emptyDescription }), _jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })] }), className: "min-h-0 flex-1" }), _jsxs("div", { className: "flex min-w-0 flex-col gap-2 border-t p-3", children: [suggestionsAfterRun && !fresh && !running && (_jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })), _jsx("p", { role: "status", "data-slot": "agent-status", className: cn("flex min-w-0 items-center gap-2 text-xs text-muted-foreground", !(progress === "line" && running) && !blocked && "sr-only"), children: blocked ? (t.waitingOnYou) : running ? (_jsxs(_Fragment, { children: [_jsx(StatusDot, { tone: "info", pulse: true }), _jsx("span", { className: "truncate", children: step ? step.name : messages.chat.runStatus("running") })] })) : null }), _jsx(Composer, { onSubmit: send, running: running, onStop: agent.stop, disabled: blocked, placeholder: placeholder, 
+    return (_jsxs("section", { ref: root, "aria-labelledby": hideHeader ? undefined : headingId, "aria-label": hideHeader ? name : undefined, "data-slot": "agent-chat", className: cn("flex min-h-0 min-w-0 flex-col bg-card text-card-foreground", className), children: [!hideHeader && (_jsxs("div", { className: "flex min-w-0 items-center gap-1 border-b px-3 py-2", children: [_jsx("h2", { id: headingId, className: "min-w-0 flex-1 truncate text-sm font-semibold", children: name }), headerActions, !hideNewConversation && _jsx(NewConversationButton, {}), onExpandedChange && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": expanded ? t.restore : t.expand, title: expanded ? t.restore : t.expand, onClick: () => onExpandedChange(!expanded), children: expanded ? _jsx(Minimize2Icon, { "aria-hidden": true }) : _jsx(Maximize2Icon, { "aria-hidden": true }) })), onClose && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": t.close, title: t.close, onClick: onClose, children: _jsx(XIcon, { "aria-hidden": true }) }))] })), progress === "steps" && view.steps.length > 0 && (_jsx(AgentProgress, { view: view, className: "border-b px-3 py-2" })), StateView && view.state !== undefined && (_jsx("div", { role: "region", "aria-label": t.sharedState, "data-slot": "agent-state", 
+                // A scrolling region is reached by keyboard (WCAG 2.1.1).
+                tabIndex: 0, className: "max-h-48 min-w-0 shrink-0 overflow-y-auto border-b px-3 py-2", children: _jsx(StateView, { state: view.state, setState: agent.setState, agent: agent }) })), _jsx(MessageList, { view: view, renderContent: renderContent, renderToolCall: drawCall, renderAfter: drawAfter, footer: footer, toolTitle: toolTitle, onApprove: (call) => agent.approve(call), onDeny: (call, reason) => agent.deny(call, reason), onRetry: () => void agent.regenerate(), empty: _jsxs("div", { className: "flex flex-col items-center gap-4 py-6", children: [empty ?? _jsx(EmptyState, { title: t.emptyTitle, description: t.emptyDescription }), _jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })] }), className: "min-h-0 flex-1" }), _jsxs("div", { className: "flex min-w-0 flex-col gap-2 border-t p-3", children: [suggestionsAfterRun && !fresh && !running && (_jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })), _jsx("p", { role: "status", "data-slot": "agent-status", className: cn("flex min-w-0 items-center gap-2 text-xs text-muted-foreground", !(progress === "line" && running) && !blocked && "sr-only"), children: blocked ? (t.waitingOnYou) : running ? (_jsxs(_Fragment, { children: [_jsx(StatusDot, { tone: "info", pulse: true }), _jsx("span", { className: "truncate", children: step ? step.name : messages.chat.runStatus("running") })] })) : null }), _jsx(Composer, { onSubmit: send, running: running, onStop: agent.stop, disabled: blocked, placeholder: placeholder, 
                         // eslint-disable-next-line jsx-a11y/no-autofocus -- the person just opened the assistant to type
                         autoFocus: autoFocus, attachments: attachments, actions: modelPicker || composerActions ? (_jsxs(_Fragment, { children: [modelPicker && _jsx(ModelPicker, { ...modelPicker }), composerActions] })) : undefined })] })] }));
 }

package/dist/agent/WorkflowRenderers.d.ts

@@ -0,0 +1,61 @@
+import * as React from "react";
+import { type DocumentReviewProps } from "../workflow/DocumentReview.js";
+import { type FormReviewProps } from "../workflow/FormReview.js";
+import { type MediaReviewProps } from "../workflow/MediaReview.js";
+import type { WorkflowQuestion } from "../workflow/question.js";
+import type { Artifact, RunStage } from "../workflow/run.js";
+import type { AgentRenderers, CustomRendererProps, InterruptRendererProps } from "./renderers.js";
+/** `calliope.run`: a run's stages as the agent reports them. Send it again with the same `id` to update. */
+export interface RunProgressValue {
+    id?: string;
+    label?: string;
+    stages: readonly RunStage[];
+}
+/** The review viewer an artifact opens in. */
+export type ArtifactReviewValue = ({
+    viewer: "document";
+} & Pick<DocumentReviewProps, "title" | "pages" | "annotations" | "signOffs" | "signOffRole">) | ({
+    viewer: "media";
+} & Pick<MediaReviewProps, "kind" | "src" | "title" | "poster" | "captions" | "duration" | "comments">) | ({
+    viewer: "form";
+} & Pick<FormReviewProps, "title" | "pages" | "fields" | "threshold">);
+/**
+ * `calliope.artifact`: an output for the person to look at, and to review
+ * when the run waits on it. `interruptId` names the run's interrupt the
+ * review answers: signing a document resolves it with `{ action: "sign-off" }`,
+ * sending a form's review with `{ action: "form-review", fields }`.
+ */
+export interface ArtifactValue {
+    id: string;
+    artifact: Artifact;
+    review?: ArtifactReviewValue;
+    interruptId?: string;
+}
+/** `calliope.question` interrupts carry a question in `metadata.question`. */
+export interface QuestionInterruptMetadata {
+    question: WorkflowQuestion;
+}
+/** The run timeline for `calliope.run` events: progress drawn in the conversation. */
+export declare function RunProgressCard({ value }: CustomRendererProps<RunProgressValue>): React.JSX.Element;
+/**
+ * An artifact the agent produced, with its review viewer (document, media or
+ * form) as the preview. While the run waits on its review, signing off or
+ * sending the form's review answers the interrupt and resumes the run.
+ */
+export declare function ArtifactReviewCard({ value, agent }: CustomRendererProps<ArtifactValue>): React.JSX.Element;
+/** A `calliope.question` interrupt: the runtime question card, its answers resuming the run. */
+export declare function QuestionInterruptCard({ interrupt, resolve }: InterruptRendererProps): React.JSX.Element;
+/**
+ * Any other open interrupt not tied to a tool call: the agent's question in
+ * its words, with approve and decline (a decline always with a reason).
+ */
+export declare function InterruptCard({ interrupt, resolve, className, }: InterruptRendererProps & {
+    className?: string;
+}): React.JSX.Element;
+/**
+ * The workflow run and review components as generative UI: `calliope.run`
+ * custom events draw the run timeline, `calliope.artifact` events draw the
+ * artifact with its document, media or form review, and `calliope.question`
+ * interrupts draw the runtime question card. Merge with the host's own.
+ */
+export declare const workflowRenderers: AgentRenderers;

package/dist/agent/WorkflowRenderers.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { ArtifactCard } from "../workflow/ArtifactCard.js";
+import { DocumentReview } from "../workflow/DocumentReview.js";
+import { FormReview } from "../workflow/FormReview.js";
+import { MediaReview } from "../workflow/MediaReview.js";
+import { RunTimeline } from "../workflow/RunTimeline.js";
+import { WorkflowQuestionCard } from "../workflow/WorkflowQuestionCard.js";
+/** The run timeline for `calliope.run` events: progress drawn in the conversation. */
+export function RunProgressCard({ value }) {
+    return (_jsx("div", { className: "min-w-0 rounded-lg border bg-card p-3", children: _jsx(RunTimeline, { stages: value.stages, label: value.label }) }));
+}
+function openInterrupt(agent, id) {
+    if (!id || agent.view.status !== "interrupted")
+        return undefined;
+    return agent.view.interrupts.find((i) => i.id === id);
+}
+/**
+ * An artifact the agent produced, with its review viewer (document, media or
+ * form) as the preview. While the run waits on its review, signing off or
+ * sending the form's review answers the interrupt and resumes the run.
+ */
+export function ArtifactReviewCard({ value, agent }) {
+    const { messages } = useUI();
+    const waiting = openInterrupt(agent, value.interruptId);
+    const [fields, setFields] = React.useState({});
+    const resolve = (payload) => waiting && agent.resolveInterrupt(waiting.id, { status: "resolved", payload });
+    const review = value.review;
+    let preview = null;
+    if (review?.viewer === "document") {
+        const { viewer: _, ...props } = review;
+        preview = (_jsx(DocumentReview, { ...props, ...(waiting
+                ? { onSignOff: () => resolve({ action: "sign-off", artifactId: value.id }) }
+                : {}) }));
+    }
+    else if (review?.viewer === "media") {
+        const { viewer: _, ...props } = review;
+        preview = _jsx(MediaReview, { ...props });
+    }
+    else if (review?.viewer === "form") {
+        const { viewer: _, ...props } = review;
+        const current = props.fields.map((f) => fields[f.id] ?? f);
+        preview = (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx(FormReview, { ...props, fields: current, ...(waiting
+                        ? {
+                            onAccept: (field) => setFields((s) => ({ ...s, [field.id]: { ...field, status: "accepted" } })),
+                            onCorrect: (field, corrected) => setFields((s) => ({
+                                ...s,
+                                [field.id]: { ...field, status: "corrected", corrected },
+                            })),
+                        }
+                        : {}) }), waiting && (_jsx(Button, { size: "sm", className: "self-end", onClick: () => resolve({
+                        action: "form-review",
+                        artifactId: value.id,
+                        fields: current.map(({ id, status, corrected }) => ({ id, status, corrected })),
+                    }), children: messages.agent.sendReview }))] }));
+    }
+    return _jsx(ArtifactCard, { artifact: value.artifact, preview: preview, headingLevel: "h3" });
+}
+/** A `calliope.question` interrupt: the runtime question card, its answers resuming the run. */
+export function QuestionInterruptCard({ interrupt, resolve }) {
+    const question = interrupt.metadata?.question;
+    const [state, setState] = React.useState("waiting");
+    return (_jsx(WorkflowQuestionCard, { question: question ?? null, state: state, onSubmit: (submission) => {
+            setState("submitting");
+            resolve({ answers: submission.answers, revision: submission.revision });
+        } }));
+}
+/**
+ * Any other open interrupt not tied to a tool call: the agent's question in
+ * its words, with approve and decline (a decline always with a reason).
+ */
+export function InterruptCard({ interrupt, resolve, className, }) {
+    const { messages } = useUI();
+    const t = messages.agent;
+    const [declining, setDeclining] = React.useState(false);
+    const [reason, setReason] = React.useState("");
+    const reasonId = React.useId();
+    return (_jsxs("section", { "aria-label": t.interrupt, "data-slot": "agent-interrupt", className: cn("flex min-w-0 flex-col gap-2 rounded-lg border border-warning-border bg-warning-bg p-3 text-sm text-warning-fg", className), children: [_jsx("p", { className: "[overflow-wrap:anywhere]", children: interrupt.message ?? messages.chat.approvalNeeded }), declining ? (_jsxs("form", { className: "flex min-w-0 flex-col gap-2", onSubmit: (event) => {
+                    event.preventDefault();
+                    if (reason.trim())
+                        resolve({ approved: false, reason: reason.trim() });
+                }, children: [_jsx("label", { htmlFor: reasonId, className: "text-xs font-medium", children: messages.chat.denyReason }), _jsx("textarea", { id: reasonId, value: reason, onChange: (event) => setReason(event.target.value), rows: 2, className: "min-w-0 rounded-md border border-input bg-background p-2 text-sm text-foreground" }), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setDeclining(false), children: t.back }), _jsx(Button, { type: "submit", variant: "destructive", size: "sm", disabled: !reason.trim(), children: t.decline })] })] })) : (_jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setDeclining(true), children: t.decline }), _jsx(Button, { size: "sm", onClick: () => resolve({ approved: true }), children: messages.chat.approve })] }))] }));
+}
+/**
+ * The workflow run and review components as generative UI: `calliope.run`
+ * custom events draw the run timeline, `calliope.artifact` events draw the
+ * artifact with its document, media or form review, and `calliope.question`
+ * interrupts draw the runtime question card. Merge with the host's own.
+ */
+export const workflowRenderers = {
+    custom: {
+        "calliope.run": RunProgressCard,
+        "calliope.artifact": ArtifactReviewCard,
+    },
+    interrupts: {
+        "calliope.question": QuestionInterruptCard,
+    },
+};

package/dist/agent/controller.d.ts

@@ -38,6 +38,20 @@ export interface AgentControllerOptions {
     /** Every AG-UI event, for the host's telemetry. */
     onEvent?: (event: AgUiEvent) => void;
 }
+/**
+ * A custom event as the conversation draws it: events whose value carries
+ * the same `id` are one item (progress updating in place), placed where the
+ * first of them arrived.
+ */
+export interface AgentCustomItem {
+    key: string;
+    name: string;
+    /** The latest value. */
+    value: unknown;
+    history: readonly unknown[];
+    /** The timeline item it arrived after ("message:<id>", "tool-call:<id>"), or null before any. */
+    after: string | null;
+}
 export interface AgentSnapshot {
     view: ChatView;
     /** True from send until the agent is done, follow-ups and browser tools included. */
@@ -49,6 +63,8 @@ export interface AgentSnapshot {
     unread: number;
     suggestions: readonly AgentSuggestion[];
     tools: readonly AgentTool[];
+    /** The conversation's custom events, grouped and placed (see `AgentCustomItem`). */
+    custom: readonly AgentCustomItem[];
 }
 export interface SendOptions {
     /** Attachments and other parts after the text (AG-UI input content). */
@@ -76,6 +92,8 @@ export declare class AgentController {
     private visible;
     private read;
     private snapshot;
+    /** Where each custom event arrived, by its index in the view. */
+    private anchors;
     private disposed;
     private connected;
     private threadSeq;
@@ -97,6 +115,7 @@ export declare class AgentController {
     private emit;
     private finishedAnswers;
     private build;
+    private customItems;
     private bind;
     /** The view the agent's own messages and state make, for a fresh start or a thread switch. */
     private fromAgent;