Home Explore Help
Register Sign In
haiany
/
deepseek-harness
mirror of https://github.com/deepseek-ai/deepseek-harness.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: 0180c5cdea
Branches Tags
deepseek-harnes...
/
packages
/
client
/
ui-primitives
/
README.md

README.md 11 KB
History Raw

description: "Shared React UI atoms for the dsh web client: controls, icons, markdown and math rendering, and the terminal/read/diff/search/web output cards (zero cordis)."

kind: "package-library"

@deepseek-ai/dsh-client-ui-primitives

English | 中文

Summary

dsh-client-ui-primitives is the web client's shared React component library: every feature plugin composes its UI from these atoms, and nothing here depends on Cordis or the slot system. It provides the control set (buttons, pills, inputs, menus, modals, toast banners, disclosure rows, hover cards, connection indicators), the icon glyphs and brand marks, positioning hooks for anchored overlays, and the content renderers for agent output: markdown with TeX math, terminal output, file reads, diffs, search results, web retrieval, and JSON inspection. The renderers are built for untrusted model output — raw HTML is dropped, links are neutralized or opened safely, and ANSI escape sequences are parsed rather than passed through. User-facing copy is supplied through label props; the feature plugin that composes an atom owns localization.

Table of Contents

Use this package

Compose feature UI from these atoms whenever the web client needs a standard control or an agent-output renderer. They render through React only and take --dsw-* design tokens from the theme, so they fit any plugin without importing the theme or the slot system.

Controls and icons

Button, Pill, Input, Menu, Modal, Tooltip, DisclosureRow, StateDot, HoverCard, Toast, ConnectionIndicator, RiskConfirmation, and the OnboardingSurface first-run takeover cover the common interaction shapes. The ic_ds_* icon set and FishLogo/BrandWordmark marks fill brand and inline-icon slots. LinkIcon draws the leading category glyph for clickable artifact links — globe, folder, code, image, document, or plain paper, all riding currentColor — and classifyLinkPath derives a file path's category from its extension. ConnectionIndicator renders a warning-colored disconnected action, a connecting label whose one-to-three dots advance every 500ms independently of retry timing, or a success-colored recovered status. Every state reserves the widest supplied label and uses fixed icon and text columns, so copy changes do not move or resize the control. Its owner supplies visibility, the recovery hold, localized labels, and the immediate-reconnect callback; the primitive uses no native title tooltip. useAnchoredPosition and useAnchoredMaxHeight keep floating panels and bottom-anchored overlays clamped to the viewport and following their anchor. HoverCard keeps its portaled preview reachable across the anchor gap and can expose a copy button through the copyText prop. Toast holds for the window its owner names through holdMs, because how long a banner has to stay depends on how much there is to read; the same value drives its unmount timer and the stylesheet's fade delay, so the two cannot disagree. rankByName is the / menu's shared candidate ranker for the command and skill sources: the query must be a case-insensitive ordered subsequence of the name; prefix hits rank first, then alignment score, then source order (ranking decision).

Rendering agent output

MarkdownText renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. While a reply streams, it freezes completed blocks, advances a top-level open fence by completed lines, and highlights that fence from saved Shiki grammar state. Completed token lines enter fixed-size React groups, so later chunks reconcile only the growing group; an unchanged fence retains that DOM when the final full parse resolves cross-document syntax (incremental renderer, streaming fence highlighting). TerminalBlock, ReadBlock, DiffBlock, SearchBlock, and WebBlock render the matching tool-result intent with copy controls, overflow handling, and ANSI processing where applicable. JsonTree and JsonBlock inspect JSON values read-only, while projectUserText projects sent user text into inline plain runs and reference chips for the message bubble and queue rows.

Localizing copy

The atoms cannot read the application locale, so every piece of user-facing copy arrives through required label props. HoverCard, TerminalBlock, JsonTree, CodeBlock, MarkdownText, JsonBlock, ConnectionIndicator, Modal, DiffBlock, ReadBlock, SearchBlock, and WebBlock accept complete localized labels. The package owns no language fallback; omission fails typechecking, and each feature maps its typed t seat into the primitive's label interface.

Understand the implementation

Implementation internals — click to expand The package is one separation: presentational React atoms with zero Cordis and zero slot knowledge, styled only through `--dsw-*` tokens, while every feature-specific concern (locale, session data, composition) stays in the composing plugin. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Public atom exports | | [`src/markdown/`](src/markdown/) | Markdown and math pipeline: micromark parsing, KaTeX typesetting, incremental streaming renderer, `CodeBlock`/`JsonBlock` | | [`src/TerminalBlock.tsx`](src/TerminalBlock.tsx) | ANSI escape parsing (`anser`) and terminal card rendering | | [`src/ReadBlock.tsx`](src/ReadBlock.tsx) / [`src/DiffBlock.tsx`](src/DiffBlock.tsx) | Read and diff cards | | [`src/SearchBlock.tsx`](src/SearchBlock.tsx) / [`src/WebBlock.tsx`](src/WebBlock.tsx) | Search and web-retrieval cards | | [`src/icons/`](src/icons/) | `ic_ds_*` glyph components and brand marks | | [`src/useAnchoredPosition.ts`](src/useAnchoredPosition.ts) / [`src/useAnchoredMaxHeight.ts`](src/useAnchoredMaxHeight.ts) | Floating-panel and overlay geometry hooks | ### Streaming markdown While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply. A final unclosed top-level fence keeps its parsed code node and sends only the last completed line plus the current partial line through the same GFM grammar; a closing fence or ambiguous parse returns to the ordinary tail path. Highlighting likewise resumes from saved Shiki grammar state and publishes only newly completed lines plus the mutable tail. `CodeBlock` seals completed lines into fixed-size React groups, reuses earlier groups, and retains the whole highlighted tree across settlement when code and language are unchanged. The settled full parse still resolves references that crossed the freeze boundary ([incremental renderer](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md), [streaming fence highlighting](../../../.agents/notes/implemented/feature/2026-08-20-web-streaming-fence-highlight.md)). ### Geometry and overflow The output cards share one geometry model: `white-space: pre` with horizontal scrolling so column-aligned content keeps its alignment, and a head-plus-tail slice behind an expand button past `maxLines` (default 16) so a long body never stretches the card. `TerminalBlock` parses ANSI into React spans with a per-line column buffer for cursor movement, honoring erase-in-line, tab stops, and character width.

Further Exploration

These pages place the atoms in the client stack and the design system.

  • ui-renderer — the React renderer that mounts the assembled application and binds slot data.
  • ui-tool — the tool-call presentation layer that composes these output cards.
  • ui-conversation — the chat surface that renders markdown replies and tool cards.
  • ui-theme — the --dsw-* token system these atoms style through.
  • Web styling — the authoritative styling rules for web client components.

Model Experience

None, as the package is a browser-side UI plugin layer that registers nothing model-facing.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

These limits define how the atoms behave at the edges; they are current package constraints, not a component roadmap.

  • Streaming defers cross-boundary reference resolution — a reference-style link or footnote whose definition sits on the other side of the incremental freeze boundary renders as literal text while the reply streams; the settled full parse at finalize resolves it.
  • A long highlighted fence retains its complete token DOM — streaming avoids re-parsing, re-tokenizing, and reconciling the completed prefix, but it does not discard old colors or virtualize token spans. Final DOM cardinality therefore still follows the fence's token count; nested/container fences and a pathological single long line remain on the general tail path.
  • Glyph-level icons are redrawn approximations — the fish logo and the sparkle mark come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
  • Pill and Input have no design source — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
  • No Active StateDot variant — the supported states are done, warning, ongoing, and error.
  • User-facing copy is required at the render site — the atoms are zero-Cordis and cannot reach ctx.locale; each feature must supply complete localized labels through the primitive's typed props (decision).
  • TerminalBlock is not a terminal emulator — it renders settled or still-running command output, not an interactive session: SGR colors, carriage return, backspace, erase-in-line, tab stops, and character width are honored; absolute cursor positioning, screen clearing, and alternate-screen sequences are stripped.

Dev Note

Working context for maintainers — click to expand None.

Runtime invariant: No companion is published. Pure props-in React atoms with no Cordis API — no events, no services, no mutable cross-plugin state; rendering contracts are asserted directly by this package's component specs.