@deepseek-ai/dsh-client-ui-primitives 0.0.1-rc.1

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-primitives`.
+* @module @deepseek-ai/dsh-client-ui-primitives/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-primitives";
+/** Cordis companion plugin name. */
+const name = "client-ui-primitives-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: pure props-in React atoms with zero cordis surface —
+* no events, no services, no mutable cross-plugin state; rendering contracts
+* are asserted directly by this package's component specs.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/BrandWordmark.d.ts

@@ -0,0 +1,9 @@
+import type { IconProps } from './icons/props.ts';
+/**
+ * Render the full brand wordmark.
+ * @param props.size - height in px (default 24; width keeps the 182:24 ratio).
+ * @param props.className - extra class for layout placement.
+ * @returns the wordmark svg (aria-hidden decorative brand art).
+ */
+export declare function BrandWordmark({ size, className }: IconProps): import("react").JSX.Element;
+//# sourceMappingURL=BrandWordmark.d.ts.map

package/lib/types/Button.d.ts

@@ -0,0 +1,18 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+/** Visual variant, each backed by its --dsw-alias-button-* token family. */
+export type ButtonVariant = 'primary' | 'ghost' | 'outline' | 'toolbar';
+/**
+ * Render a button.
+ * @param props.variant - visual family (default 'ghost').
+ * @param props.size - 'md' 36px capsule (figma Button) or 'sm' 28px compact.
+ * @param props.icon - optional leading 16px icon node.
+ * @returns the button element; native button attributes pass through.
+ */
+export declare function Button({ variant, size, icon, className, children, ...rest }: {
+    variant?: ButtonVariant;
+    size?: 'md' | 'sm';
+    icon?: ReactNode;
+    className?: string | undefined;
+    children?: ReactNode;
+} & ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;
+//# sourceMappingURL=Button.d.ts.map

package/lib/types/ConnectionBanner.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Render the reconnecting banner.
+ * @param props.reconnecting - true while the connection is in backoff/retry.
+ * @param props.label - banner text; the owner passes localized copy (this
+ * package is cordis-free, so copy arrives via props).
+ * @returns the banner, or null when connected.
+ */
+export declare function ConnectionBanner({ reconnecting, label }: {
+    reconnecting: boolean;
+    label?: string | undefined;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=ConnectionBanner.d.ts.map

package/lib/types/DiffBlock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Output lines shown before the height cap collapses the middle. Matches
+ * {@link DEFAULT_TERMINAL_MAX_LINES} so a diff card and a terminal card cut a
+ * long body at the same place.
+ */
+export declare const DEFAULT_DIFF_MAX_LINES = 16;
+/**
+ * One file's change, in the shape {@link DiffBlock} draws. Structurally the
+ * render-intent contract's `FileDiff`, redeclared here so this primitive stays
+ * free of the tool contract (the terminal card's decoupling, applied to diffs).
+ */
+export interface DiffHunk {
+    /** The changed file's path, drawn verbatim as the hunk's header (the tool's model-facing path). */
+    path: string;
+    /** Prior content, or `null` for a new file / an overwrite (nothing on the removed side). */
+    oldText: string | null;
+    /** Content after the change (the added side). */
+    newText: string;
+}
+export interface DiffBlockProps {
+    /** One entry per applied hunk, in file order; empty renders nothing. */
+    diffs: DiffHunk[];
+    /** Height cap in body lines before the middle collapses (default {@link DEFAULT_DIFF_MAX_LINES}). */
+    maxLines?: number | undefined;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+}
+/**
+ * Render a file mutation as an inline diff surface.
+ * @param props - see {@link DiffBlockProps}.
+ * @returns the diff block element.
+ */
+export declare function DiffBlock({ diffs, maxLines, className }: DiffBlockProps): import("react").JSX.Element | null;
+//# sourceMappingURL=DiffBlock.d.ts.map

package/lib/types/DisclosureRow.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+/** Shared 24px disclosure chrome for compact flow rows. */
+export interface DisclosureRowProps {
+    icon: ReactNode;
+    title: string;
+    open: boolean;
+    expandable: boolean;
+    onToggle: () => void;
+    /** Makes the complete title row the disclosure target. */
+    expandOnRowClick?: boolean | undefined;
+    /** Replaces the collapsed icon with a chevron while the row is hovered. */
+    previewChevron?: boolean | undefined;
+    /** Keeps `collapsedContent` inline while open. */
+    keepContentWhenOpen?: boolean | undefined;
+    collapsedContent?: ReactNode;
+    children?: ReactNode;
+    className?: string | undefined;
+    rowClassName?: string | undefined;
+    leadingClassName?: string | undefined;
+    chevronClassName?: string | undefined;
+    titleClassName?: string | undefined;
+}
+/**
+ * Render one disclosure header and its controlled expanded content.
+ * @param props - Visual content, controlled state, and interaction policy.
+ * @returns the disclosure row.
+ */
+export declare function DisclosureRow({ icon, title, open, expandable, onToggle, expandOnRowClick, previewChevron, keepContentWhenOpen, collapsedContent, children, className, rowClassName, leadingClassName, chevronClassName, titleClassName, }: DisclosureRowProps): import("react").JSX.Element;
+//# sourceMappingURL=DisclosureRow.d.ts.map

package/lib/types/FishLogo.d.ts

@@ -0,0 +1,9 @@
+import type { IconProps } from './icons/props.ts';
+/**
+ * Render the fish logo.
+ * @param props.size - width in px (default 24; height keeps the 23.16:17.04 ratio).
+ * @param props.className - extra class for layout placement.
+ * @returns the logo svg (aria-hidden; pair with the wordmark for accessibility).
+ */
+export declare function FishLogo({ size, className }: IconProps): import("react").JSX.Element;
+//# sourceMappingURL=FishLogo.d.ts.map

package/lib/types/HoverCard.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+/**
+ * Render an anchor with a hover-triggered preview card.
+ * @param props.anchor - the hover target (rendered in place inside a wrapper span).
+ * @param props.content - card content; the pointer may rest on it, so it is
+ * readable and selectable, but it carries no dismissal affordance of its own.
+ * @param props.openDelayMs - hover dwell before the card shows (default 500).
+ * @param props.disabled - suppress opening; turning true closes an open card.
+ * @param props.copyText - optional primary value copied by activation and
+ * included in the card's accessible name.
+ * @param props.copyLabel - accessible activation-label prefix (default "复制").
+ * @param props.copiedLabel - visible success label (default "复制成功").
+ * @returns anchor wrapper with the conditional portaled card.
+ */
+export declare function HoverCard({ anchor, content, openDelayMs, disabled, copyText, copyLabel, copiedLabel, }: {
+    anchor: ReactNode;
+    content: ReactNode;
+    openDelayMs?: number;
+    disabled?: boolean;
+    copyText?: string | undefined;
+    copyLabel?: string | undefined;
+    copiedLabel?: string | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=HoverCard.d.ts.map

package/lib/types/Input.d.ts

@@ -0,0 +1,11 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+/**
+ * Render a text input with an optional leading icon.
+ * @param props.icon - optional 16px leading icon node.
+ * @returns wrapper span containing the native input; input attributes pass through.
+ */
+export declare function Input({ icon, className, ...rest }: {
+    icon?: ReactNode;
+    className?: string;
+} & InputHTMLAttributes<HTMLInputElement>): import("react").JSX.Element;
+//# sourceMappingURL=Input.d.ts.map

package/lib/types/JsonTree.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Display copy for the tree's copy affordance; the owner passes localized
+ * labels (this package is cordis-free, so copy arrives via props). Every
+ * field defaults to the current built-in value, so existing consumers render
+ * unchanged.
+ */
+export interface JsonTreeLabels {
+    /** Menu item: copy the raw primitive value. */
+    copyValue: string;
+    /** Menu item: copy the value as compact JSON (primitive rows). */
+    copyJson: string;
+    /** Menu item: copy the property path. */
+    copyPath: string;
+    /** Menu item: copy the value as pretty-printed JSON. */
+    copyPrettyJson: string;
+    /** Menu item: copy the value as compact JSON (object rows). */
+    copyCompactJson: string;
+    /** Copy-button state label after a successful copy. */
+    copied: string;
+    /** Copy-button state label after a failed copy. */
+    copyFailed: string;
+    /** Expander aria label while expanded. */
+    collapseNode: string;
+    /** Expander aria label while collapsed. */
+    expandNode: string;
+    /** Copy-button tooltip, given the current action label. */
+    copyButtonTitle: (action: string) => string;
+}
+/** Props for the read-only, token-themed JSON tree. */
+export interface JsonTreeProps {
+    /** Parsed JSON object or array. */
+    data: object | unknown[];
+    /** Accessible label for the tree. */
+    label?: string;
+    /** Optional positioning class owned by the caller. */
+    className?: string | undefined;
+    /** Whether JSON rows expose copy actions. */
+    copyable?: boolean;
+    /** Whether the top-level object or array is always expanded. */
+    expandTopLevel?: boolean;
+    /** Localized display copy; omitted fields keep the built-in defaults. */
+    labels?: Partial<JsonTreeLabels> | undefined;
+}
+/**
+ * Render parsed JSON as a compact, keyboard-accessible inspector tree.
+ * @param props - Parsed data, accessible label, and display options.
+ * @returns A read-only JSON tree with an optionally fixed-open top level.
+ */
+export declare function JsonTree({ data, label, className, copyable, expandTopLevel, labels, }: JsonTreeProps): import("react").JSX.Element;
+//# sourceMappingURL=JsonTree.d.ts.map

package/lib/types/Menu.d.ts

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+/** Selectable row (optionally with a nested submenu). */
+export interface MenuItem {
+    id: string;
+    label: ReactNode;
+    disabled?: boolean;
+    /** Leading icon (figma .Menu_cell gap 8). */
+    icon?: ReactNode;
+    /** Destructive row: error-colored text/icon and danger hover fill. */
+    danger?: boolean;
+    /** Nested card opened to the right on hover/focus. */
+    submenu?: readonly MenuItem[];
+}
+/** Hairline between item groups (not selectable). */
+export interface MenuSeparator {
+    type: 'separator';
+    id: string;
+}
+/** Non-interactive heading row above a group of items. */
+export interface MenuLabel {
+    type: 'label';
+    id: string;
+    text: string;
+}
+/** One primary-menu entry: a row, a separator, or a heading label. */
+export type MenuEntry = MenuItem | MenuSeparator | MenuLabel;
+/**
+ * Render an anchored dropdown menu.
+ * @param props.open - whether the list is showing (owner-controlled).
+ * @param props.anchor - the trigger element (rendered in place).
+ * @param props.items - selectable rows and optional separators.
+ * @param props.selectedId - row shown as selected.
+ * @param props.onSelect - row click callback (not called for disabled rows or submenu parents that only open children).
+ * @param props.onClose - invoked on outside click or Escape.
+ * @param props.align - list alignment against the anchor (default 'start').
+ * @param props.side - open below (`bottom`, default) or above (`top`) the anchor.
+ * @param props.portal - render the list into document.body, fixed-positioned
+ * from the anchor rect (repositions on scroll/resize while open). Use when an
+ * ancestor's overflow clipping would crop the in-place list; default false
+ * keeps the pure-CSS in-place behavior.
+ * @param props.closeOnPointerLeave - close the list once the pointer has left
+ * both trigger and list for the pointer grace (default false keeps it open
+ * until outside click/Escape/selection). The grace makes the 4px trigger->list
+ * gap and a brief overshoot survivable; coming back cancels the close.
+ * @param props.compact - use reduced menu typography and spacing.
+ * @param props.getAnchorRect - portal mode only: supply the anchor rect
+ * directly (e.g. from a host-owned trigger button) instead of measuring the
+ * Menu's own wrapper span. Required when the wrapper isn't itself laid out at
+ * the trigger (render-prop anchors, effect-positioned proxies — measuring the
+ * wrapper there races the host's layout effects). Called on open and on every
+ * scroll/resize; return null to skip placement for that frame.
+ * @param props.footer - rows pinned below the scrolling items area, separated
+ * by a hairline; they stay visible while the items above scroll.
+ * @returns anchor wrapper with the conditional list.
+ */
+export declare function Menu({ open, anchor, items, selectedId, onSelect, onClose, align, side, portal, closeOnPointerLeave, compact, getAnchorRect, footer, className }: {
+    open: boolean;
+    anchor: ReactNode;
+    items: readonly MenuEntry[];
+    footer?: readonly MenuEntry[];
+    selectedId?: string | undefined;
+    onSelect: (id: string) => void;
+    onClose: () => void;
+    align?: 'start' | 'end';
+    side?: 'bottom' | 'top' | 'right';
+    portal?: boolean;
+    closeOnPointerLeave?: boolean;
+    compact?: boolean;
+    getAnchorRect?: () => DOMRect | null;
+    className?: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=Menu.d.ts.map

package/lib/types/Modal.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+/**
+ * Render a centered modal over a blurred page mask.
+ * @param props.open - whether the dialog is showing.
+ * @param props.onClose - Escape or mask click.
+ * @param props.title - dialog heading (aria-label in every mode).
+ * @param props.closeLabel - accessible close-button label.
+ * @param props.description - optional supporting sentence under the title.
+ * @param props.children - body (inputs, etc.).
+ * @param props.footer - action row (Cancel / Create).
+ * @param props.contentClassName - optional class for a scrollable content region.
+ * @param props.headless - render children directly in the card (no default
+ * header/close/body chrome) for dialogs whose figma frame owns its own
+ * header structure; mask, card, Escape, and aria-label remain.
+ * @param props.closeLabel - close-button aria label; the owner passes
+ * localized copy (this package is cordis-free, so copy arrives via props).
+ * @returns null when closed; otherwise the overlay tree.
+ */
+export declare function Modal({ open, onClose, title, closeLabel, description, children, footer, className, contentClassName, headless, }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    closeLabel?: string;
+    description?: string;
+    children?: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+    contentClassName?: string;
+    headless?: boolean;
+}): import("react").ReactPortal | null;
+//# sourceMappingURL=Modal.d.ts.map

package/lib/types/OnboardingSurface.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+/**
+ * Render the onboarding takeover chrome (mask + opaque stage) around one
+ * step's content and keep the application root inert while mounted.
+ * @param props.children - the step's page content, centered on the stage.
+ * @returns the body-portaled overlay tree.
+ */
+export declare function OnboardingSurface({ children }: {
+    children: ReactNode;
+}): import("react").ReactPortal;
+//# sourceMappingURL=OnboardingSurface.d.ts.map

package/lib/types/Pill.d.ts

@@ -0,0 +1,13 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+/**
+ * Render a pill chip. Interactive when onClick is supplied (renders a button);
+ * otherwise a static span.
+ * @param props.active - selected/active visual state.
+ * @returns pill element.
+ */
+export declare function Pill({ active, className, children, onClick, ...rest }: {
+    active?: boolean;
+    className?: string | undefined;
+    children?: ReactNode;
+} & ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;
+//# sourceMappingURL=Pill.d.ts.map

package/lib/types/ReadBlock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Content lines shown before the height cap collapses the middle. Matches
+ * TerminalBlock's default so a long read and a long command output cut at the
+ * same place in the same flow.
+ */
+export declare const DEFAULT_READ_MAX_LINES = 16;
+/** One line of the read window: its file line number and its text (no trailing newline). */
+export interface ReadBlockLine {
+    /** 1-based line number in the file (a window past an offset keeps the file's own numbering). */
+    number: number;
+    /** The line's text, already truncated to the read tool's per-line cap. */
+    text: string;
+}
+export interface ReadBlockProps {
+    /** Banner label (the file path, or a tool-supplied replacement title); omitted draws no label. */
+    label?: string | undefined;
+    /** The returned window's lines, in file order, each keeping its file line number. */
+    lines: readonly ReadBlockLine[];
+    /** Exact total line count in the file, for the "showing N of M" note when the read is a window. */
+    totalLines: number;
+    /** Grammar hint (a file-extension-derived language id); unknown or absent = plain monospace. */
+    lang?: string | undefined;
+    /** Height cap in content lines before the middle collapses (default {@link DEFAULT_READ_MAX_LINES}). */
+    maxLines?: number | undefined;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+}
+/**
+ * Render a read tool result as a line-numbered, optionally syntax-highlighted
+ * file view.
+ * @param props - see {@link ReadBlockProps}.
+ * @returns the read block element.
+ */
+export declare function ReadBlock({ label, lines, totalLines, lang, maxLines, className, }: ReadBlockProps): import("react").JSX.Element;
+//# sourceMappingURL=ReadBlock.d.ts.map

package/lib/types/RiskConfirmation.d.ts

@@ -0,0 +1,19 @@
+export interface RiskConfirmationProps {
+    open: boolean;
+    title: string;
+    description: string;
+    acknowledgeLabel: string;
+    cancelLabel: string;
+    confirmLabel: string;
+    acknowledged: boolean;
+    disabled?: boolean;
+    onAcknowledgedChange: (acknowledged: boolean) => void;
+    onCancel: () => void;
+    onConfirm: () => void;
+}
+/**
+ * Render one in-page confirmation whose primary action is unavailable until
+ * the caller-controlled acknowledgement is checked.
+ */
+export declare function RiskConfirmation({ open, title, description, acknowledgeLabel, cancelLabel, confirmLabel, acknowledged, disabled, onAcknowledgedChange, onCancel, onConfirm, }: RiskConfirmationProps): import("react").JSX.Element;
+//# sourceMappingURL=RiskConfirmation.d.ts.map

package/lib/types/SearchBlock.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Result rows shown before the height cap collapses the middle. Matches
+ * {@link DEFAULT_TERMINAL_MAX_LINES} so a search card and a terminal card cut a
+ * long result at the same place.
+ */
+export declare const DEFAULT_SEARCH_MAX_LINES = 16;
+/** One matched line inside a {@link SearchFileGroup}: its 1-based line number and text. */
+export interface SearchBlockLineMatch {
+    /** 1-based line number of the match within its file. */
+    lineNumber: number;
+    /** The matched line text, as the tool surfaced it. */
+    line: string;
+}
+/** One file's grouped matches, in first-seen file order. */
+export interface SearchFileGroup {
+    /** The file the matches belong to (the display path). */
+    path: string;
+    /** The file's matched lines, in output order. */
+    matches: SearchBlockLineMatch[];
+}
+/** Fields both search shapes carry (the render site positions; this component draws). */
+interface SearchBlockCommon {
+    /**
+     * Whether the tool capped the inline result: the shape carries only the
+     * retained results, not every result the search found. The banner summary
+     * folds the pre-cap `total` in (`显示 X / 共 N …`) so the card never presents a
+     * capped result as complete.
+     */
+    truncated: boolean;
+    /** Total results the search found before capping (equals the retained count when not `truncated`). */
+    total: number;
+    /** Height cap in rows before the middle collapses (default {@link DEFAULT_SEARCH_MAX_LINES}). */
+    maxLines?: number | undefined;
+    /** Extra class merged onto the wrapper. */
+    className?: string | undefined;
+}
+/** Props for the grouped-matches (`grep`) shape. */
+export interface SearchMatchesBlockProps extends SearchBlockCommon {
+    kind: 'matches';
+    /** Matched lines grouped by file, in first-seen file order. */
+    files: SearchFileGroup[];
+}
+/** Props for the flat-path (`glob`) shape. */
+export interface SearchPathsBlockProps extends SearchBlockCommon {
+    kind: 'paths';
+    /** The discovered paths, in the tool's result order (the retained page when `truncated`). */
+    paths: string[];
+}
+/** {@link SearchBlock} props: one card, two `kind`-discriminated shapes. */
+export type SearchBlockProps = SearchMatchesBlockProps | SearchPathsBlockProps;
+/**
+ * Render a completed search as a grouped-matches or flat-path card.
+ * @param props - see {@link SearchBlockProps}.
+ * @returns the search block element.
+ */
+export declare function SearchBlock(props: SearchBlockProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=SearchBlock.d.ts.map

package/lib/types/StateDot.d.ts

@@ -0,0 +1,15 @@
+/** Four-color state semantic (green done / amber user-attention / blue running ring / red error). */
+export type StateDotState = 'done' | 'warning' | 'ongoing' | 'error';
+/**
+ * Render a state dot.
+ * @param props.state - which of the four states to show.
+ * @param props.size - outer diameter in px (default 10, the figma size).
+ * @param props.className - extra class for layout placement.
+ * @returns the dot element (aria-hidden; pair with text for accessibility).
+ */
+export declare function StateDot({ state, size, className }: {
+    state: StateDotState;
+    size?: number | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=StateDot.d.ts.map

package/lib/types/TerminalBlock.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Output lines shown before the height cap collapses the middle. Matches the
+ * TUI transcript's default tool-output budget so both front ends cut a long
+ * command's output at the same place.
+ */
+export declare const DEFAULT_TERMINAL_MAX_LINES = 16;
+/**
+ * Display copy for the terminal surface; the owner passes localized labels
+ * (this package is cordis-free, so copy arrives via props). Every field
+ * defaults to the current built-in value, so existing consumers render
+ * unchanged.
+ */
+export interface TerminalBlockLabels {
+    /** Status pill text for a signal-terminated command. */
+    signal: (signal: string) => string;
+    /** Status pill text for a non-zero exit code. */
+    exitCode: (exitCode: number) => string;
+    /** Run-state text while the command is still running. */
+    running: string;
+    /** Run-state text for a signal or non-zero-exit settle. */
+    failed: string;
+    /** Run-state text for a clean settle. */
+    done: string;
+    /** Copy-button idle label. */
+    copy: string;
+    /** Copy-button label during the post-copy confirmation window. */
+    copied: string;
+    /** Placeholder when a settled command produced no visible output. */
+    noOutput: string;
+    /** Collapse-toggle aria label while expanded. */
+    collapseAria: string;
+    /** Collapse-toggle text while expanded. */
+    collapse: string;
+    /** Expand-toggle aria label while capped, given the hidden line count. */
+    expandAria: (hidden: number) => string;
+    /** Expand-toggle text while capped, given the hidden line count. */
+    expand: (hidden: number) => string;
+}
+export interface TerminalBlockProps {
+    /** The command line, rendered verbatim after the prompt label. */
+    command: string;
+    /** Working directory for the prompt label; absent renders a plain `$`. */
+    cwd?: string | undefined;
+    /** Absolute home directory, so a cwd equal to it collapses to `~`; absent disables that collapse. */
+    home?: string | undefined;
+    /** The command's output text; may contain ANSI escape sequences. */
+    output?: string | undefined;
+    /** Settled exit code; a non-zero value renders the status pill. */
+    exitCode?: number | undefined;
+    /** Settled terminating signal name; any value renders the status pill, taking precedence over the exit code. */
+    signal?: string | undefined;
+    /** The command is still running: the block shows the prompt line alone. */
+    running?: boolean | undefined;
+    /** Height cap in output lines before the middle collapses (default {@link DEFAULT_TERMINAL_MAX_LINES}); Infinity disables the cap. */
+    maxLines?: number | undefined;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+    /** Localized display copy; omitted fields keep the built-in defaults. */
+    labels?: Partial<TerminalBlockLabels> | undefined;
+}
+/**
+ * Render a shell command as a terminal surface.
+ * @param props - see {@link TerminalBlockProps}.
+ * @returns the terminal block element.
+ */
+export declare function TerminalBlock({ command, cwd, home, output, exitCode, signal, running, maxLines, className, labels, }: TerminalBlockProps): import("react").JSX.Element;
+//# sourceMappingURL=TerminalBlock.d.ts.map

package/lib/types/Tooltip.d.ts

@@ -0,0 +1,30 @@
+import type { FocusEventHandler, MouseEventHandler, ReactElement, Ref } from 'react';
+/** Bubble placement relative to the anchor. */
+export type TooltipSide = 'right' | 'bottom' | 'top';
+/** Props Tooltip injects into its anchor child; the child's own handlers are chained ahead of the tooltip's. */
+interface AnchorProps {
+    ref?: Ref<HTMLElement> | undefined;
+    onMouseEnter?: MouseEventHandler | undefined;
+    onMouseLeave?: MouseEventHandler | undefined;
+    onFocus?: FocusEventHandler | undefined;
+    onBlur?: FocusEventHandler | undefined;
+}
+/**
+ * Attach a hover/focus tooltip to an anchor element.
+ * @param props.label - bubble text.
+ * @param props.side - placement relative to the anchor (default 'right').
+ * @param props.delayMs - hover delay in milliseconds; keyboard focus remains immediate.
+ * @param props.disabled - suppress the bubble while true; the anchor renders identically so
+ * toggling never remounts it (which would cut its CSS transitions).
+ * @param props.children - a single anchor element; its own ref (callback or object) is forwarded alongside the tooltip's.
+ * @returns the cloned anchor plus a fixed-position bubble while hovered/focused.
+ */
+export declare function Tooltip({ label, side, delayMs, disabled, children }: {
+    label: string;
+    side?: TooltipSide;
+    delayMs?: number;
+    disabled?: boolean;
+    children: ReactElement<AnchorProps>;
+}): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Tooltip.d.ts.map

package/lib/types/WebBlock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One citeable source drawn in a search card: the projection of the contract's
+ * `WebSource`, with the optional fields kept optional so a provider that
+ * returned only a URL still renders (its hostname becomes the label).
+ */
+export interface WebSourceView {
+    /** The source URL; becomes a safe external link when it is http(s). */
+    url: string;
+    /** The source title; when absent the URL's hostname labels the link. */
+    title?: string | undefined;
+    /** A short excerpt or summary shown under the link. */
+    snippet?: string | undefined;
+    /** Publication/crawl timestamp, a provider-supplied string shown under the link. */
+    publishedAt?: string | undefined;
+}
+/** A `web_search` card: an optional answer over a capped citation list. */
+export interface WebSearchBlockProps {
+    kind: 'search';
+    /** The provider-generated answer, rendered as markdown above the sources. */
+    answer?: string | undefined;
+    /** The cited sources, in provider order. */
+    sources: WebSourceView[];
+    /** True when the tool cut the source list to its result cap. */
+    truncated: boolean;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+}
+/** A `web_fetch` card: the retrieval summary for one fetched URL. */
+export interface WebFetchBlockProps {
+    kind: 'fetch';
+    /** The final URL after allowed redirects; becomes a safe external link when http(s). */
+    url: string;
+    /** HTTP status code of the fetched response. */
+    statusCode: number;
+    /** True when the provider or the output cap cut the fetched content. */
+    truncated: boolean;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+}
+/** A completed web retrieval card, discriminated by `kind`. */
+export type WebBlockProps = WebSearchBlockProps | WebFetchBlockProps;
+/**
+ * Render a completed web retrieval as a structured card.
+ * @param props - see {@link WebBlockProps}; `kind` selects the search or fetch body.
+ * @returns the web card element.
+ */
+export declare function WebBlock(props: WebBlockProps): import("react").JSX.Element;
+//# sourceMappingURL=WebBlock.d.ts.map