Transcript view

Transcript is the desktop app's chat transcript as a React component. It renders prompts, replies, thinking, tool calls and output, edit diffs, subagents, notices, compactions and run receipts. The fixture below has every row kind. Expand a tool call or the subagent, and switch the density.

FullFullCompactCompact

Row iconsRow iconsNo iconsNo icons

api-errors.md

Rate limit the chat endpoint: 20 requests a minute per IP, and tell clients how long to wait when it trips. The chart shows who hit it last night.

Used find the chat route and any limiter, edited a file, used run the server tests3

2 earlier messages

• The chat route now takes a token from a per-IP bucket: 20 a minute, with bursts of 5. Over the limit it answers 429 with a Retry-After header, so clients know how long to wait.

  All 44 server tests pass.

  Opus 5.538s4$0.0717k1.1k

Document it in docs/server.mdx, then commit.

Used document the limit in a subagent, then commit, 1 worker1

• Documented under Limits in docs/server.mdx and committed as 83dfea7.

  Opus 5.552s3$0.0912k980

Mount it#

Transcript takes events you already hold (a recorded session, your own store). HostTranscript reads them from the ChatHost in context, like the session list.

import type { ChatEvent } from 'zidane-ui/chat/headless'
import 'zidane-ui/styles.css'
import { Transcript } from 'zidane-ui/chat'

export function Replay({ id, events }: { id: string, events: readonly ChatEvent[] }) {
  return <Transcript events={events} streaming={false} sessionId={id} />
}

HostTranscript takes sessionId and onOpenSession, plus every other Transcript prop. It reads host.transcript(id), a store of { events, running, hydrated, hasEarlier?, loadingEarlier? }. It adds these parts:

• A loading line until hydrated is true.
• An "Earlier messages" control while hasEarlier is set. The control calls the loadEarlier method of the transcript store.
• The row actions, bound to the host.

import type { ChatHost } from 'zidane-ui/chat/headless'
import { ChatProvider, HostTranscript } from 'zidane-ui/chat'

export function Conversation({ host, id, onOpen }: { host: ChatHost, id: string, onOpen: (id: string) => void }) {
  return (
    <ChatProvider host={host}>
      <HostTranscript sessionId={id} onOpenSession={onOpen} />
    </ChatProvider>
  )
}

The preview runs on createFixtureHost({ sessions, transcripts }), which serves static events.

A prompt that the session's own user did not type in a window (a Slack or GitHub channel, an orchestration event) carries an origin on its user-prompt event. The transcript shows a short label above it. A channel participant reads Alice · slack, the session's user on another surface reads via slack, and an event shows its source. The row's origin is a PromptOrigin from zidane-ui/chat/headless: { kind, source, sender? }, zidane's TextOrigin without messageId. Override the words (promptOriginSender, promptOriginSomeone, promptOriginVia) through LabelsProvider.

Options#

options takes any subset of zidane's display settings of the same names, so stored settings pass straight through. Missing fields fall back to DEFAULT_TRANSCRIPT_OPTIONS (zidane's defaults). Each setting and its default: Display settings.

import type { TranscriptOptions } from 'zidane-ui/chat'

const COMPACT: Partial<TranscriptOptions> = { transcriptDensity: 'compact', showThinking: false }

<HostTranscript sessionId={id} options={COMPACT} />

Row icons#

Each row starts with an icon: you, the agent, and how a step went (running, done, failed). showRowIcons: false (default true) drops them and the column they sit in, so the rows start at the edge. Switch it in the preview above.

Without the icons, a row's own line shows what only its icon did:

HostTranscript drops the ring of its earlier-history control too. A row your app draws itself (a renderer slot) reads the option with useRowIcons() from zidane-ui/chat/transcript.

import type { TranscriptOptions } from 'zidane-ui/chat'

const PLAIN: Partial<TranscriptOptions> = { showRowIcons: false }

<HostTranscript sessionId={id} options={PLAIN} />

Diagrams#

A reply's ``````mermaid`` fences draw as diagrams. The kit renders them with Pele, which turns Mermaid into SVG. renderDiagrams: false (default true) shows them as code. Switch it in the preview:

• Where. Only fences in prose (Markdown) become diagrams. The CodeBlock slot still draws tool inputs and the files a tool read, so a .mmd file shows its source.
• Streaming. A fence still open at the end of a streaming reply draws from the source so far, at most every 120 ms, with Pele's render(). A source that does not parse yet keeps the last drawing, never an error. Once the fence closes, the diagram is mounted (mount()): it lays itself out again when its column resizes, and it zooms. Every drawing is kept per source (a bounded cache), so the closed fence, or a row that mounts again, paints at once.
• Zoom. The frame's controls zoom out, zoom in and fit, next to the source toggle and Copy, with Pele's own buttons off. Pinch, Cmd/Ctrl-wheel, double-click and drag work too. A plain wheel scrolls the transcript.
• Source. The source view is highlighted in the code theme. @pierre/highlights has no Mermaid grammar, so the kit lexes Mermaid itself (code/mermaid-lexer.ts) in the theme's own syntax colors, in the highlighter's worker and cache. Any mermaid or mmd code block gets it, a .mmd file a tool read included.
• Cost. Pele loads when the first diagram comes near the view, and each diagram type loads on its first use. A transcript with no diagrams loads nothing. A diagram is drawn when it comes near the view, and it lays itself out again when its column resizes. A row that mounts again keeps the height its diagram had, so the view does not move.
• Theme. The SVG reads --pele-* variables. .zg-diagram sets them from the theme tokens: the panel is --zg-code-bg, nodes are --zg-raised, subgraphs are --zg-tray, lines and borders are --zg-text-muted and --zg-border, and charts use the accent, then the status colors in Pele's hue order (warn, success, danger, ...). Labels use --zg-font-chat and --zg-font-mono at --zg-font-size-chat. A theme switch repaints through CSS alone. A font change from the appearance preferences measures the labels again. To restyle diagrams, set any --pele-* variable on .zg-diagram (Pele theming).
• Safety. The source is model output. Pele escapes text, filters styles and limits size. The kit also turns off images (no network requests) and links. A source that Pele cannot draw shows as highlighted code, with the reason under it.

Outside a transcript, wrap Markdown in MarkdownDiagrams to choose, or draw one source with MermaidDiagram. Both come from zidane-ui/chat/transcript:

import { Markdown, MarkdownDiagrams, MermaidDiagram } from 'zidane-ui/chat/transcript'

<MarkdownDiagrams enabled={settings.renderDiagrams}>
  <Markdown>{reply}</Markdown>
</MarkdownDiagrams>

<MermaidDiagram code={'flowchart LR\n  A --> B'} />

Two optional props:

• turnMenu ({ onContextMenu, prefetch? }) puts a right-click handler on each prompt and each settled reply. Render the menu as the children of the transcript.
• selection turns on select-turn mode. selected is the turn under the cursor. registerStops gives you the turns that the cursor can move between.

Renderer slots#

Parts that need app services (file badges, session titles, text previews) render through slots with plain defaults. Override any subset with TranscriptRenderersProvider. The desktop app adds its file badges here.

import type { CodeBlockSlotProps, TranscriptRenderers } from 'zidane-ui/chat/transcript'
import { TranscriptRenderersProvider } from 'zidane-ui/chat/transcript'

function Highlighted({ code, language }: CodeBlockSlotProps) {
  return <pre data-language={language}>{highlight(code, language)}</pre>
}

// A module constant: a new object re-renders every row.
const RENDERERS: Partial<TranscriptRenderers> = { CodeBlock: Highlighted }

<TranscriptRenderersProvider value={RENDERERS}>
  <HostTranscript sessionId={id} />
</TranscriptRenderersProvider>

Actions#

Each action except sessionId is optional. Without an action, its control is hidden. HostTranscript binds most of them for you. With Transcript alone, pass them through TranscriptActionsProvider.

import type { TranscriptActions } from 'zidane-ui/chat/transcript'
import { TranscriptActionsProvider } from 'zidane-ui/chat/transcript'

const actions = useMemo<TranscriptActions>(
  () => ({ sessionId: id, openSession: setActive, resume: prompt => composer.send(prompt) }),
  [id, setActive],
)

<TranscriptActionsProvider value={actions}>
  <Transcript events={events} streaming={running} sessionId={id} />
</TranscriptActionsProvider>

Chips, cards and badges#

ProseMarkdown is the kit's Markdown with chips: inline code that names a file, a folder or a branch, #123 and commit SHAs, links with their site's icon, and extension references (a ticket id, an issue URL). Pass it as the Markdown slot. PromptEcho draws a sent prompt with the composer's badges, and InlineChipText a receipt line with chips. Hovering a chip opens one ChipCard. Right-clicking a badge opens the BadgeMenu (copy, add to prompt, open, plus the extensions' items).

Chips read what they need from optional ChatHost members. A member the host leaves out keeps its chips plain:

createServerHost resolves path chips on the server's disk (files.resolvePaths) and fills chips.commit with git.commit, offers references and badges over the server's extensions, chips.context over sessions.contextBreakdown (labeled as the composer's gauge is), and no siteIcons: the web app's Content-Security-Policy (img-src 'self' data: blob:) keeps the page from loading other sites' images, and a server fetching any origin a transcript names is not worth the exposure, so links show the globe.

What a chip resolves against comes from MarkdownContext: the session's cwd, the repo's web base (#123 and SHAs link there), the server a server session's files are on, and open(path, kind, event), which opens a file or folder chip. BadgeMenuProvider takes the focused composer (where "Add to prompt" goes) and system (opens and reveals paths). OpenSessionContext makes a #chat card's title open that chat.

import { ChatProvider } from 'zidane-ui/chat'
import { BadgeMenuProvider, MarkdownContext, ProseMarkdown } from 'zidane-ui/chat/transcript'
import { createFixtureHost } from 'zidane-ui/chat/testing'

const host = createFixtureHost({
  sessions: [],
  extras: { paths: { '/repo': { 'README.md': { kind: 'file', path: '/repo/README.md' } } } },
})

<ChatProvider host={host}>
  <BadgeMenuProvider>
    <MarkdownContext.Provider value={{ cwd: '/repo', repoWebBase: 'https://github.com/acme/repo', open }}>
      <ProseMarkdown>{'See `README.md`, fixed in #12.'}</ProseMarkdown>
    </MarkdownContext.Provider>
  </BadgeMenuProvider>
</ChatProvider>

Inside a ChatProvider, a fixture's extras (ChatTranscriptFixture) serve each member from static data.

Search, select-turn and the turn menu#

Performance#

Follow these rules to keep long sessions fast.

Reference#

zidane-ui/chat/transcript, zidane-ui/chat, zidane-ui/chat/headless.