packages web design

Web design

Active contributors: Zachary BENSALEM

Purpose

web/design is the @prime-agent/web-design UI kit. It contains everything the browser renders for the Qredence web chat: the chat surface itself, the tool-call cards, the app chrome around it, and the generative UI renderer for OpenUI output. The kit is a standalone package under the web/ pnpm workspace and is not part of the upstream PrimeIntellect-ai/prime-agent merge. It consumes the wire types from web/protocol (@prime-agent/web-protocol) and is rendered by the frontend host in web/app.

Browser code rules apply here: components talk HTTP (NDJSON + SSE) and never import @earendil-works/*. All styling uses Tailwind v4. The kit exports three surfaces, each under its own directory:

• agent-elements is the reusable chat surface (message turns, input bar, tool cards).
• fleet-pi is the Qredence app chrome: header, session picker, command palette, right panel, and the settings dialog.
• openui renders generative UI programs returned by the agent.

Directory layout

web/design/
├── package.json
├── scripts/
│   ├── message-turn-identity-check.tsx
│   └── openui-render-check.tsx
└── src/
    ├── styles/globals.css
    ├── hooks/                      # use-mobile, use-proximity-hover
    ├── lib/
    │   ├── canvas-utils.ts, horizontal-resize.ts, workspace-path-nav.ts,
    │   │   layout-constants.ts, notify.ts, utils.ts, springs.ts
    │   └── pi/chat-helpers.ts
    └── components/
        ├── ...                     # shared primitives: button, card, dialog,
        │                           #   sidebar, table, field, command, etc.
        ├── agent-elements/
        │   ├── agent-chat.tsx, message-list.tsx, message-turns.tsx,
        │   │   user-message.tsx, markdown.tsx, input-bar.tsx,
        │   │   composer-loader.tsx, spiral-loader.tsx, text-shimmer.tsx
        │   ├── input/              # model-picker, effort-picker, suggestions,
        │   │                       #   question-bar, input-bar-surface, popover
        │   ├── question/           # question-tool, question-prompt
        │   ├── tools/              # tool-renderer, tool-registry, per-tool cards
        │   ├── utils/              # tool-part-normalizer, tool-adapters,
        │   │                       #   format-tool, chat-message-parts, cn
        │   ├── hooks/              # use-chat-auto-scroll and others
        │   ├── types.ts, types/    # public prop types, timeline types
        │   └── icons/              # source-icons, file-ext-icon
        ├── fleet-pi/
        │   ├── chat/               # fleet-pi-agent-chat, fleet-pi-input-bar,
        │   │                       #   fleet-pi-tool-renderer, fork-picker-dialog
        │   ├── layout/             # chat-header, chat-workspace-layout,
        │   │                       #   right-panel-shell, right-panel-context,
        │   │                       #   right-panel-registry
        │   ├── primitives/         # chrome-pill, discrete-tab, settings-pane,
        │   │                       #   item-row, surface, centered-loader
        │   ├── pi/                 # resources/workspace/artifacts panels,
        │   │                       #   settings-dialog, settings-sections,
        │   │                       #   config-panel/, resizable-canvas,
        │   │                       #   chat-command-palette
        │   └── styles/             # tokens.ts
        └── openui/                 # openui-renderer, inline-renderer, charts,
                                    #   data, tones, openui-library, openui-utils

Key abstractions

Type	Path	Description
AgentChat	web/design/src/components/agent-elements/agent-chat.tsx	Top-level chat surface: empty state, input bar, suggestions, message list.
MessageList	web/design/src/components/agent-elements/message-list.tsx	Scroll container that groups messages into turns and applies streaming/planning behavior.
AssistantTurn / UserTurn	web/design/src/components/agent-elements/message-turns.tsx	Turn components plus buildAssistantElements, the pure walk over message parts that assigns stable keys and dispatches tool parts.
InputBar	web/design/src/components/agent-elements/input-bar.tsx	Composer: textarea, suggestions, slash commands, attachments, question bar, typing animation.
ModelPicker / EffortPicker	web/design/src/components/agent-elements/input/model-picker.tsx and effort-picker.tsx	Toolbar pickers for model selection and thinking effort.
ToolRenderer	web/design/src/components/agent-elements/tools/tool-renderer.tsx	Dispatches a tool-* part to the matching tool card component.
toolRegistry	web/design/src/components/agent-elements/tools/tool-registry.ts	Metadata (icon, title, subtitle) for generic tools and MCP tool name parsing.
SpiralLoader	web/design/src/components/agent-elements/spiral-loader.tsx	Lottie-based streaming indicator used in planning rows and tool cards.
GenerativeTextRenderer	web/design/src/components/openui/openui-renderer.tsx	Segments assistant content and renders OpenUI programs through the library.
openUILibrary	web/design/src/components/openui/openui-library.tsx	Component registry (Button, Card, charts, DataTable, etc.) passed to @openuidev/react-lang.
FleetPiAgentChat	web/design/src/components/fleet-pi/chat/fleet-pi-agent-chat.tsx	Qredence-specific AgentChat wiring that injects the OpenUI text renderer and the fleet tool renderer.
ChatHeader pieces	web/design/src/components/fleet-pi/layout/chat-header.tsx	Account menu, session controls, kernel status chip, new-session button.
SettingsDialog	web/design/src/components/fleet-pi/pi/settings-dialog.tsx	App settings modal with six sections and a discard flow for dirty drafts.
RIGHT_PANEL_REGISTRY	web/design/src/components/fleet-pi/layout/right-panel-registry.tsx	Declares the Resources, Workspace, and Artifacts panel definitions.

How it works

A ChatMessage from the wire has a parts array of ChatStreamEvent fragments (text, error, or tool-* parts). The message pipeline normalizes parts, groups messages into turns, then hands each tool part to the tool renderer, which dispatches on part.type.

flowchart LR
    A[ChatStreamEvent part] --> B{part.type}
    B -- "tool-Bash" --> C[BashTool]
    B -- "tool-IPython" --> D[IpythonTool]
    B -- "tool-Edit / tool-Write" --> E[EditTool]
    B -- "tool-WebSearch / tool-Grep / tool-Glob" --> F[SearchTool]
    B -- "tool-PlanWrite" --> G[PlanTool]
    B -- "tool-TodoWrite" --> H[TodoTool]
    B -- "tool-Task / tool-Agent" --> I[ToolGroup]
    B -- "tool-Thinking" --> J[ThinkingTool]
    B -- "tool-Question" --> K[QuestionTool]
    B -- "tool-mcp__*" --> L{has custom renderer?}
    L -- yes --> M[CustomRenderer]
    L -- no --> N[McpTool]
    B -- "other tool-*" --> O{toolRegistry lookup}
    O -- found --> P[GenericTool]
    B -- "fallback" --> Q[GenericTool]

Loading

Lifecycle derives from part state: input-streaming renders as a streaming/pending card, output-available as success, output-error as error. See features/tool-cards.md for the card lifecycle and features/streaming-chat.md for streaming behavior.

The assistant text renderer is OpenUI-aware. GenerativeTextRenderer runs segmentOpenUIContent to split content into markdown and fenced OpenUI blocks, then renders each program through @openuidev/react-lang with openUILibrary.

flowchart LR
    A[assistant content] --> B[segmentOpenUIContent]
    B --> C{segment type}
    C -- markdown --> D[Markdown]
    C -- openui --> E[Renderer with openUILibrary]
    E --> F{parse errors?}
    F -- yes --> G[OpenUIDiagnostics]
    F -- no --> H[charts / data / tones / primitives]

Loading

Integration points

• web/app is the frontend host that imports and mounts this kit. See packages/web-app.md.
• web/protocol defines the ChatStreamEvent, ChatMessage, and settings types this kit renders. See packages/web-protocol.md.
• web/server adapts the agent session and produces the frames this kit consumes. See packages/web-server.md.
• The web architecture overview lives in overview/architecture.md.

Entry points for modification

• Add or change a tool card: edit web/design/src/components/agent-elements/tools/tool-renderer.tsx (dispatch) and web/design/src/components/agent-elements/tools/tool-registry.ts (metadata), and add the component under web/design/src/components/agent-elements/tools/.
• Change chat composition, empty state, or suggestions: web/design/src/components/agent-elements/agent-chat.tsx.
• Change the composer: web/design/src/components/agent-elements/input-bar.tsx and the files under web/design/src/components/agent-elements/input/.
• Add a settings tab: extend SETTINGS_SECTIONS in web/design/src/components/fleet-pi/pi/settings-sections.ts and add a pane in web/design/src/components/fleet-pi/pi/settings-dialog.tsx.
• Add an OpenUI component: register it in web/design/src/components/openui/openui-library.tsx.
• Change panel layout or the three right-panel views: web/design/src/components/fleet-pi/layout/right-panel-shell.tsx and the panel files under web/design/src/components/fleet-pi/pi/.

Key source files

File	Role
web/design/src/components/agent-elements/tools/tool-renderer.tsx	Core tool dispatch by part.type.
web/design/src/components/agent-elements/tools/tool-registry.ts	Tool metadata and MCP tool name parsing.
web/design/src/components/agent-elements/tools/tool-adapters.ts	Maps protocol tool parts to a timeline ToolStep.
web/design/src/components/agent-elements/tools/tool-part-normalizer.ts	Parses stringified input/output/result JSON on tool parts.
web/design/src/components/agent-elements/tools/format-tool.ts	Tool status derivation, elapsed time, and memo comparison.
web/design/src/components/agent-elements/message-turns.tsx	Turn grouping, stable keys, and the buildAssistantElements walk.
web/design/src/components/agent-elements/hooks/use-chat-auto-scroll.ts	Auto-scroll pin/release and resize observation.
web/design/src/components/openui/openui-library.tsx	OpenUI component registry.
web/design/src/components/openui/openui-utils.ts	Content segmentation into markdown/OpenUI blocks.
web/design/src/styles/globals.css	Tailwind v4 theme, Inter variable font, light/dark tokens.
web/design/scripts/message-turn-identity-check.tsx	Verifies assistant element keys are stable and unique.
web/design/scripts/openui-render-check.tsx	Parses and renders a canned OpenUI program, asserting markup.

Scripts and checks

The package exposes two rendering check scripts that npm run check runs under check:rendering:

• web/design/scripts/message-turn-identity-check.tsx runs via check:message-identities. It renders message turns and asserts the React keys produced by getAssistantToolElementKey and buildAssistantElements are unique and stable.
• web/design/scripts/openui-render-check.tsx runs via check:openui. It parses a canned OpenUI program against the library schema, renders it statically and into a happy-dom instance, and asserts expected markup (including that a malicious chart color cannot break out of a <style> tag).

Styling

web/design/src/styles/globals.css is the Tailwind v4 entry point. It imports Tailwind, tw-animate-css, shadcn, and the Inter variable font, then maps the semantic theme tokens (--color-*, --radius-*) and defines :root and .dark variable blocks in oklch. Light and dark theming is driven by the dark custom variant. The kit also ships component CSS files for agent UI (agent-ui.css), the fleet chat (fleet-pi-agent-chat.css), and discrete tabs (discrete-tab.css).