agentic-ui-kit 0.2.1 → 0.4.0

package/README.md

@@ -174,7 +174,60 @@ edit into an open file. If the stream breaks or the arguments aren't valid JSON,
 
 A tool's `view` sets how it looks in the chat: `label`, `subtitle`, `summary`, a `Detail` component for the
 expanded row and the approval card, and `ask` for the approval question. `Block` renders a call on its own
-instead of inside the activity group.
+instead of inside the activity group; `Card` draws a card under the group while the call keeps its row (job
+cards, a diff with Apply/Undo). A backend can set `data` on a tool call (with `part.update` / `part.end`):
+display data for these views, kept apart from the `result` the model sees. `MarkdownLinksProvider` draws
+chosen links in replies your way, e.g. a job link as a job row.
+
+## Inline visuals
+
+The model can draw something interactive in its reply, and it fills in while the model writes. The kit is
+only the UI: your harness names the tools and writes the prompt; the kit suggests both and draws the result.
+Register the views under your tool names. Full guide: https://bushshrub.github.io/agentic-ui-kit/custom-harness/connecting-your-agent/
+
+**Your components (recommended).** Register components with a JSON Schema for their props (with zod:
+`z.toJSONSchema`). Give the model `showUiTool(specs)` from `agentic-ui-kit/core`: it passes JSX as a string,
+which the chat draws element by element as it streams. Answer each call with
+`checkUiMarkupCode(markup, specs).feedback`, so the model learns what to fix (line, component, allowed props).
+
+```tsx
+const components: UiComponent[] = [
+  { name: "Metric", description: "A key number with a label.", props: metricSchema, render: Metric },
+  { name: "Stack", description: "Children in a column.", children: true, render: Stack },
+];
+// server: tools: [showUiTool(components.map(({ render, ...spec }) => spec)), ...]
+<UiComponentsProvider components={components} persist={store}>
+  <ToolViewsProvider tools={{ ...defaultToolViews, show_ui: uiMarkupToolView() }}>
+    <ChatView {...chat} />
+  </ToolViewsProvider>
+</UiComponentsProvider>;
+```
+
+Inside a component, `useUiAction()` runs an action from its props (`uiActionSchema`: set a state key, send
+a message, open a URL, copy), and `useUiState()` reads and writes the widget's state. `persist` keeps each
+widget's state across reloads. Also available: ` ```ui ` blocks in reply text (`uiMarkupGuide`,
+`checkUiMarkup`) and JSON trees in a tool call (`renderUiTool`, `uiTreeToolView`, `checkUiTree`).
+
+**Sandboxed HTML.** For maps, charts and anything free-form: give the model `visualizeTool` and put
+`visualizeGuide` in its instructions, register `show_widget: widgetToolView()`, and answer calls with
+`checkWidgetCode(code, allow).feedback`. Widgets render in a `WidgetFrame`: an iframe with
+`sandbox="allow-scripts"` only and a CSP that blocks every request, themed with your `--chat-*` variables.
+The same frame hosts MCP App UIs (MCP Apps spec 2026-01-26: `ui/initialize`, tool input and result,
+`tools/call`); the kit never fetches anything itself, your `readResource` does.
+
+```tsx
+<ChatView
+  {...chat}
+  widgets={{
+    allow: { resourceDomains: ["https://unpkg.com", "https://tile.openstreetmap.org"] }, // the most any widget may load
+    onCallTool: (name, args) => mcp.callTool(name, args), // MCP App UIs; leave out to turn it off
+    onWidgetError: ({ partId, message }) => report(partId, message), // script errors, to send back to the model
+  }}
+/>
+```
+
+A widget's `sendPrompt(text)` sends through `onSend`, and its links open in a new tab; set either callback to
+`undefined` to turn it off. `ChatTranscript` widgets cannot send messages or call tools.
 
 ## Theming
 
@@ -203,6 +256,21 @@ add `background: "theme"`, which uses the Shiki theme's own background and text
 animations even when the OS asks for less). It sets `data-chat-motion` on the element; an app that does not use
 `ChatTheme` can put `data-chat-motion="reduce"` on `<html>` instead.
 
+Every string the kit shows (text, aria-labels, placeholders) can be reworded or translated with `labels` on
+`ChatTheme`. Keys you leave out keep the English default; labels with values in them are functions, and `locale`
+sets the language of relative times and dates (default: the browser's). The keys are listed in `ChatLabels`.
+
+```tsx
+<ChatTheme labels={{ copy: "Copier", moreOptionsFor: (title) => `Plus d'options pour ${title}`, locale: "fr" }}>
+```
+
+Every icon is swappable the same way with `icons` (Lucide by default). Pass SVG elements; the kit sizes and
+colors them with CSS. The keys are listed in `ChatIcons`.
+
+```tsx
+<ChatTheme icons={{ copy: <MyCopy />, send: <MySend /> }}>
+```
+
 The full list of variables is at the top of
 [`packages/react/src/styles.css`](packages/react/src/styles.css).
 
@@ -214,11 +282,50 @@ The React package has four layers, each built only from the ones before it:
 | ---------- | --------------------------------------------------------------------------------------------- |
 | Primitives | `Button`, `IconButton`, `Menu`, `ContextMenu`, `Modal`, `Drawer`, `Panel`, `Tooltip`, `CodeBlock`, `ChatTheme` |
 | Hooks      | `useChat`, `sseTransport`, `AgentProvider`, `useAgentTool`, `useAgentContext`, `useSmoothText` |
-| Components | `Composer`, `ModelPicker`, `MessageList`, `ActivityGroup`, `ApprovalCard`, `Markdown`, `ChatHeader`, `ChatList`, `ContextPanel` |
+| Components | `Composer`, `ModelPicker`, `MessageList`, `ActivityGroup`, `ApprovalCard`, `Markdown`, `ChatHeader`, `ChatList`, `ContextPanel`, `WidgetFrame`, `UiTree` |
 | Views      | `ChatView`, `AppShell`, `Sidebar`                                                             |
 
 Use `ChatView` for the whole thing, or build your own layout from the components.
 
+## What you can change, and what is fixed
+
+The kit has opinions about how a chat behaves and is laid out, and stays out of the way of how it looks as
+your brand and of the space it sits in.
+
+**Yours to change**
+
+- Colors, fonts, radii, shadows: `--chat-*` variables.
+- Text sizes: variables for message text (`--chat-message-font-size`), code (`--chat-code-font-size`),
+  interface text (`--chat-ui-font-size`), small interface text (`--chat-ui-font-size-sm`), the user bubble
+  (`--chat-bubble-font-size`) and activity rows (`--chat-activity-font-size`). A theme can set them per
+  `[data-chat-density]`.
+- Width and density: `contentWidth`, and `density="full" | "panel" | "inline"` for a page, a side panel or a
+  box in a form.
+- Code themes and motion on or off: `ChatTheme` props.
+- Wording and locale: `ChatTheme labels`, see Theming. Icons: `ChatTheme icons`, Lucide by default.
+- Content: the `header`, `footer`, `notice`, `emptyState` and `disclaimer` slots, custom parts through
+  `renderPart`, and tool views through `useChatTool`.
+- Inline visuals: which domains widgets may load and which of their abilities are on (`widgets`), and the
+  components the model may compose (`UiComponentsProvider`).
+
+**Fixed on purpose**
+
+- Streaming: the paced reveal, the word fade, following the reply while you are at the bottom and leaving you
+  alone when you scroll up. Small changes here make streaming feel janky.
+- Animations and their timings. Only on or off, for reduced motion.
+- The layout: user messages in bubbles on the right, replies as full-width text, thinking and tool calls
+  folded into one activity row with a summary.
+- Message actions: which ones you turn on is yours; where they sit (under the message, on hover) is not.
+- Spacing inside the chrome. `density` covers the cases that need it to be tighter.
+- Accessibility and keyboard behavior: focus rings, roles, Enter to send, menus and dialogs from react-aria.
+- Markdown: only safe HTML in replies, streaming-safe parsing.
+- When long messages fold and how tool calls group.
+- The widget sandbox: `allow-scripts` only, the CSP, messages only from the widget's own frame, the height cap,
+  scripts running once the markup is complete. The action set of your components' trees.
+
+A new setting has to change the look or fit a different container. A setting that changes how the chat
+behaves needs a strong case. If you need different behavior, build your own layout from the components.
+
 Bundle size: Markdown, KaTeX and Shiki are most of it, about 345 KB gzipped for a chat page. Shiki's language
 grammars load on demand.
 

package/dist/core.js

@@ -1 +1,96 @@
-export { a as activityTokens, o as applyEvent, s as awaitingToolCalls, c as estimateTokens, t as formatEvent, r as isActivityPart, l as outputTokens, p as parsePartialJson, n as readEventStream, u as reduceEvents, d as resolveEffort, f as settleToolCall, i as toBlocks } from "./sse-BA_ebMcH.js";
+import { A as salvageJson, C as awaitingToolCalls, D as resolveEffort, E as reduceEvents, O as settleToolCall, S as applyEvent, T as outputTokens, _ as formatEvent, a as readUiValue, b as toBlocks, c as uiMarkupGuide, d as isStateRef, f as matchesSchema, g as uiActionSchema, h as schemaErrors, i as parseUiMarkup, k as parsePartialJson, l as uiMarkupLanguage, m as renderUiToolName, n as checkUiMarkupCode, o as showUiTool, p as renderUiTool, r as findUiBlocks, s as showUiToolName, t as checkUiMarkup, u as checkUiTree, v as readEventStream, w as estimateTokens, x as activityTokens, y as isActivityPart } from "./ui-markup-DtMYer7I.js";
+// ../core/src/visualize.ts
+/** The tool definition to give the model. Same shape as a page tool's `ToolSpec`. */
+const visualizeTool = {
+	name: "show_widget",
+	description: "Draw an interactive visual inline in your reply: a chart, diagram, map, calendar, calculator, planner. Write an HTML fragment or an <svg> in widget_code; it runs in a sandboxed frame that matches the chat's theme. Follow the visual design guide in your instructions.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			widget_code: {
+				type: "string",
+				description: "An HTML fragment (no <html>, <head> or <body>) or an <svg>. Inline <style> and <script> are allowed."
+			},
+			title: {
+				type: "string",
+				description: "Short snake_case name for the visual, e.g. gym_week."
+			},
+			loading_messages: {
+				type: "array",
+				items: { type: "string" },
+				minItems: 1,
+				maxItems: 4,
+				description: "1-4 short lines shown while you write it, e.g. \"Finding free slots\"."
+			}
+		},
+		required: ["widget_code"]
+	}
+};
+/** Design guide for the system prompt when the visualize tool is on. */
+const visualizeGuide = `## Visuals (show_widget)
+Use show_widget when a visual says it better than text: data to compare, a plan to adjust, a place to see, a
+process to step through. Keep explaining in text around it; the widget is not the whole answer.
+
+How the frame works
+- widget_code is a fragment: no <!doctype>, <html>, <head> or <body>. Put <style> first, then markup, then <script>.
+- It renders while you write it; scripts run once it is complete, in order. Put scripts last.
+- No network unless the host allows it: no fetch, no external images or fonts. Inline your data.
+- The background is transparent and the frame sizes itself to your content. Add no outer margin or padding,
+  no outer border or card around the whole widget, and no fixed height on the root.
+- Two globals: sendPrompt(text) sends a message as the user (for "Add these to my calendar", "Explain this"),
+  openLink(url) opens an http(s) link. Prefer local state (JavaScript in the widget) over round trips: filter,
+  toggle, recalculate and animate in place; use sendPrompt only for what needs you.
+
+Look
+- Use the chat's theme variables, never hard-coded colors or fonts: var(--chat-fg) text, var(--chat-muted) and
+  var(--chat-subtle) secondary text, var(--chat-surface) and var(--chat-raised) fills, var(--chat-border) and
+  var(--chat-divider) lines, var(--chat-hover) hover, var(--chat-accent) with var(--chat-accent-fg) for the one
+  thing that matters most, var(--chat-check) good, var(--chat-warning), var(--chat-danger) bad;
+  var(--chat-font-sans), var(--chat-font-mono); var(--chat-ui-font-size), var(--chat-ui-font-size-sm);
+  var(--chat-radius-sm), var(--chat-radius-md), var(--chat-radius-lg).
+- Quiet by default: thin borders, few fills, one accent. Readable labels, aligned numbers, no decoration.
+- Set apart what you added or changed from what was already there: your proposals in the accent with a small
+  "New" (or "Changed") tag, existing data quiet. The user must see at a glance what is yours.
+- Make it work on a narrow screen (down to 320px wide) and with a keyboard: real <button>s, visible focus.`;
+const originOf = (url) => {
+	try {
+		return new URL(url).origin.toLowerCase();
+	} catch {
+		return;
+	}
+};
+/**
+* Checks widget code before it reaches the user, so a harness can send problems back to the model as the
+* tool result. `allow` is what the host lets widgets load (the same `allow` as the chat's `widgets`).
+*/
+function checkWidgetCode(html, allow = {}, toolName = visualizeTool.name) {
+	const errors = [];
+	const warnings = [];
+	if (typeof html !== "string" || !html.trim()) errors.push("widget_code: required, an HTML fragment or an <svg>");
+	else {
+		if (/<!doctype|<html[\s>]|<head[\s>]|<body[\s>]/i.test(html)) errors.push("Send a fragment: no <!doctype>, <html>, <head> or <body>.");
+		const allowed = (allow.resourceDomains ?? []).map((d) => d.toLowerCase().replace(/\/$/, ""));
+		const fits = (origin) => allowed.some((a) => a === origin || a.includes("*.") && origin.endsWith(a.slice(a.indexOf("*.") + 1)) && origin.startsWith(a.slice(0, a.indexOf("*."))));
+		const blocked = /* @__PURE__ */ new Set();
+		for (const m of html.matchAll(/(?:src|href)\s*=\s*["']?(https?:\/\/[^"'\s>]+)|url\(\s*["']?(https?:\/\/[^"')\s]+)|@import\s+["'](https?:\/\/[^"']+)/gi)) {
+			const origin = originOf(m[1] ?? m[2] ?? m[3] ?? "");
+			if (origin && !fits(origin) && !/<a\s[^>]*$/i.test(html.slice(0, m.index))) blocked.add(origin);
+		}
+		if (blocked.size) errors.push(`Blocked by the sandbox: ${[...blocked].join(", ")}. ${allowed.length ? `Only ${allowed.join(", ")} may be loaded.` : "Nothing external may be loaded."} Inline it instead.`);
+		if (!(allow.connectDomains ?? []).length && /\bfetch\s*\(|XMLHttpRequest|new\s+WebSocket|EventSource\s*\(/.test(html)) errors.push("Network calls (fetch, XHR, WebSocket) are blocked: inline the data.");
+		if (/\b(localStorage|sessionStorage|document\.cookie|indexedDB)\b/.test(html)) errors.push("Storage (localStorage, cookies, indexedDB) is not available in the sandbox: keep state in variables.");
+		if (/\b(alert|confirm|prompt)\s*\(/.test(html)) errors.push("alert/confirm/prompt are blocked: show it in the widget, or use sendPrompt(text).");
+		if (/<form[\s>]/i.test(html) && /type\s*=\s*["']?submit/i.test(html)) warnings.push("Form submits are blocked: handle the button's click in a script.");
+		const colors = new Set([...html.matchAll(/(?<![\w-])(#[0-9a-f]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\))/gi)].map((m) => m[1].toLowerCase()));
+		if (colors.size) warnings.push(`Hard-coded colors (${[...colors].slice(0, 5).join(", ")}${colors.size > 5 ? ", ..." : ""}): use var(--chat-*) so it matches the theme.`);
+	}
+	const ok = errors.length === 0;
+	const lines = [...errors, ...warnings].map((e) => `- ${e}`).join("\n");
+	return {
+		ok,
+		errors,
+		warnings,
+		feedback: ok && !warnings.length ? "Shown to the user." : ok ? `Shown. To fit the chat better next time:\n${lines}` : `Shown, but it will not work as written. Fix these and call ${toolName} again, without remarking on the fix to the user:\n${lines}`
+	};
+}
+export { activityTokens, applyEvent, awaitingToolCalls, checkUiMarkup, checkUiMarkupCode, checkUiTree, checkWidgetCode, estimateTokens, findUiBlocks, formatEvent, isActivityPart, isStateRef, matchesSchema, outputTokens, parsePartialJson, parseUiMarkup, readEventStream, readUiValue, reduceEvents, renderUiTool, renderUiToolName, resolveEffort, salvageJson, schemaErrors, settleToolCall, showUiTool, showUiToolName, toBlocks, uiActionSchema, uiMarkupGuide, uiMarkupLanguage, visualizeGuide, visualizeTool };