@qilin-agent/client-ui-chat 0.0.0-stage → 3.1.3

package/lib/types/client/chat/use-chat-viewport.d.ts

@@ -0,0 +1,169 @@
+/** Turn-aware DOM scrolling and geometry, without history-loading or follow policy. */
+import { type RefObject } from 'react';
+import type { ChatScrollPosition } from '../contract/slots.ts';
+import type { ChatSnapshot } from '../contract/snapshot.ts';
+import { ScrollFollow, type ViewportMetrics } from './use-scroll-follow.ts';
+export type { ViewportMetrics } from './use-scroll-follow.ts';
+/** Scroll geometry attributed against the last acknowledged position. */
+export interface ViewportScroll {
+    readonly metrics: ViewportMetrics;
+    readonly movedByReader: boolean;
+}
+/** Actual clamped scroll result, including any known semantic anchor and turn. */
+export interface ViewportLanding {
+    readonly metrics: ViewportMetrics;
+    readonly position: ChatScrollPosition | null;
+    readonly turn: number | null;
+}
+interface ViewportEvents {
+    scroll: (event: ViewportScroll) => void;
+    scrollEnd: () => void;
+    resize: () => void;
+    interact: () => void;
+}
+/** Owns one Chat scrollport's DOM operations, event listeners, and size observer. */
+export declare class ChatViewport {
+    private elements;
+    private observer;
+    private events;
+    private turns;
+    private observation;
+    private resized;
+    private readerIntent;
+    private paging;
+    /**
+     * Bind to the containing scrollport and observe content and viewport sizes.
+     * @param list - Chat root inside an optional shared conversation scrollport.
+     * @param column - ordered outer Node/Group boxes; its size changes invalidate cached landings.
+     */
+    attach(list: HTMLElement, column: HTMLElement): void;
+    /** Disconnect DOM resources and clear observations for the detached view. */
+    detach(): void;
+    /**
+     * Connect business policy without changing DOM listener ownership.
+     * @param events - business handlers for scroll and layout changes.
+     * @returns a disposer that disconnects only these handlers.
+     */
+    connect(events: ViewportEvents): () => void;
+    /**
+     * Adopt the loaded turn anchors without querying the DOM.
+     * @param turns - ordered loaded turns from the committed Chat snapshot.
+     */
+    updateTurns(turns: ReturnType<ChatSnapshot['navigation']['items']>): void;
+    /**
+     * Resolve the tail from the committed turn index.
+     * @returns the latest loaded turn, or null for an empty window.
+     */
+    get latestTurn(): number | null;
+    /** Discard geometry-dependent landing knowledge while retaining scroll attribution. */
+    invalidate(): void;
+    /**
+     * Accept a sampled reader position without retaining a known landing.
+     * @param metrics - settled reader position used as the next attribution baseline.
+     */
+    acknowledge(metrics: ViewportMetrics): void;
+    /**
+     * Consume the pending transcript resize.
+     * A delivery that arrives with one is the browser's layout compensation,
+     * not a reader choice, so it must not re-anchor the semantic position.
+     * @returns whether the transcript resized since the previous sample.
+     */
+    consumeResize(): boolean;
+    /**
+     * Consume reader input recorded since the previous sample.
+     * Geometry alone cannot separate a reader scroll from the browser's layout
+     * compensation, so a transcript that moved with reader input present is the
+     * reader's own choice.
+     * @returns whether wheel, touch, pointer, key, or find-in-page input arrived.
+     */
+    consumeReaderIntent(): boolean;
+    /**
+     * Compare the current scroll geometry with the last acknowledged position.
+     * @returns current metrics and movement attribution, or null while detached.
+     */
+    readScroll(): ViewportScroll | null;
+    private metrics;
+    private anchor;
+    /**
+     * Capture visible transcript content, excluding Turn controls that relocate when history expands.
+     * @returns a visible semantic anchor, or null when no anchor can be resolved.
+     */
+    capturePosition(): ChatScrollPosition | null;
+    /**
+     * Approximate the active Turn by binary-searching outer Node/Group boxes.
+     * Gaps retain the last visited Turn candidate, not necessarily the immediate predecessor.
+     * A known landing bypasses measurement while its position is unchanged.
+     * @param metrics - reusable scroll metrics; omitted callers request a fresh read.
+     * @returns the Turn near the reading line, or null while detached or empty.
+     */
+    readVisibleTurn(metrics?: ViewportMetrics | null): number | null;
+    /**
+     * Align a known loaded turn and return its actual clamped position.
+     * A split Node anchor selects its first visible part.
+     * @param turn - loaded turn to align below the scrollport's top edge.
+     * @returns the actual landing, or null when its anchor is unavailable.
+     */
+    scrollToTurn(turn: number): ViewportLanding | null;
+    /**
+     * Align the nearest available fallback for an unavailable turn anchor.
+     * @param turn - minimum turn number for a mounted fallback row.
+     * @returns the fallback landing, or null when no eligible row exists.
+     */
+    scrollToTurnAtOrAfter(turn: number): ViewportLanding | null;
+    /**
+     * Restore a semantic anchor with a raw-position fallback.
+     * @param position - semantic scroll memory; raw top is used only if its row is absent.
+     * @returns the actual landing, or null while detached.
+     */
+    restore(position: ChatScrollPosition): ViewportLanding | null;
+    /**
+     * Re-align the reader's own settled row after a layout change moved it.
+     * A missing row leaves the scrollport untouched: the raw position is only
+     * meaningful for the row it was sampled against.
+     * @param position - semantic position sampled while the reader owned the transcript.
+     * @returns the actual landing, or null when the row is absent or still aligned.
+     */
+    restoreReaderRow(position: ChatScrollPosition | null): ViewportLanding | null;
+    /** Retain the first eligible transcript seat in DOM order; selection reads no geometry. */
+    beginPaging(): void;
+    /**
+     * Retain one old row and its inner/outer offsets for paging and later content growth.
+     * @param position - an explicit landing to retain; omitted callers capture the current reading position.
+     */
+    beginPreserving(position?: ChatScrollPosition | null): void;
+    private retain;
+    /** Release paging ownership and its content-size observation. */
+    stopPreserving(): void;
+    /**
+     * Expose retained paging ownership to navigation and resize policy.
+     * @returns whether a paging row is retained for subsequent layout changes.
+     */
+    get preserving(): boolean;
+    /**
+     * Compensate inner scrolling first, then the outer scrollport, within their actual scroll ranges.
+     * An inner write pauses its bound follow controller so the reading anchor takes priority.
+     * @returns the actual landing, or null when no visible retained row remains.
+     */
+    preserve(): ViewportLanding | null;
+    /**
+     * Align the scrollport with its current floor.
+     * @param follow - independent follow intent and scrolling controller.
+     * @returns the actual floor landing, or null while detached.
+     */
+    scrollToBottom(follow: ScrollFollow): ViewportLanding | null;
+    private align;
+    private write;
+    private readonly onScroll;
+    private readonly onScrollEnd;
+    private readonly onIntent;
+}
+/**
+ * Bind viewport resource ownership to the component's layout lifetime.
+ * @returns one viewport owner and the element refs attached for this mount.
+ */
+export declare function useChatViewport(): {
+    viewport: ChatViewport;
+    listRef: RefObject<HTMLDivElement>;
+    columnRef: RefObject<HTMLDivElement>;
+};
+//# sourceMappingURL=use-chat-viewport.d.ts.map

package/lib/types/client/chat/use-disclosure.d.ts

@@ -0,0 +1,15 @@
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { UseDisclosure } from '../contract/slots.ts';
+/**
+ * Own one initially collapsed disclosure without an external subscription.
+ * @param version - reset generation; unchanged generations retain local open state.
+ * @returns the open state, an explicit setter, and a toggle action.
+ */
+export declare function useDisclosure(version?: number): ReturnType<UseDisclosure>;
+/**
+ * Bind a Hook without subscribing until a component calls it.
+ * @param reset - stable source whose version advances when the seat is hidden by its Turn.
+ * @returns a Hook with independent open state for each invocation.
+ */
+export declare function bindDisclosure(reset: ObservableSnapshot<number>): UseDisclosure;
+//# sourceMappingURL=use-disclosure.d.ts.map

package/lib/types/client/chat/use-process-scroll.d.ts

@@ -0,0 +1,23 @@
+/** Capped process-group scrolling and fades over the shared follow controller. */
+import { type DOMAttributes, type RefObject } from 'react';
+interface ScrollEdges {
+    readonly canScrollUp: boolean;
+    readonly canScrollDown: boolean;
+}
+/**
+ * Observe one group's body and content without coupling its follow intent to the outer transcript.
+ * Wheel, touchstart, any pointerdown, and unprevented scroll keys interrupt active animations,
+ * including events from editable controls; subsequent position sampling determines follow intent.
+ * @param bodyRef - capped scrolling body.
+ * @param contentRef - uncapped content whose size reports growth.
+ * @param open - local disclosure state.
+ * @param grouped - whether the display mode retains the group's height cap.
+ * @returns edge fades, DOM event bindings, and one-shot positioning for manual opening.
+ */
+export declare function useProcessScroll(bodyRef: RefObject<HTMLDivElement>, contentRef: RefObject<HTMLDivElement>, open: boolean, grouped: boolean): {
+    edges: ScrollEdges;
+    events: Pick<DOMAttributes<HTMLDivElement>, 'onScroll' | 'onWheel' | 'onTouchStart' | 'onPointerDown' | 'onKeyDown'>;
+    initialize: (position: 'top' | 'bottom') => void;
+};
+export {};
+//# sourceMappingURL=use-process-scroll.d.ts.map

package/lib/types/client/chat/use-scroll-follow.d.ts

@@ -0,0 +1,105 @@
+/** Scroll position, maximum top, and viewport height from one geometry read. */
+export interface ViewportMetrics {
+    readonly top: number;
+    readonly floor: number;
+    readonly height: number;
+}
+/**
+ * Read one scrollport without measuring its children.
+ * @param element - scrolling element.
+ * @returns current position and range.
+ */
+export declare function scrollMetrics(element: HTMLElement): ViewportMetrics;
+/** One scrollport's follow intent; native animation progress does not count as reader movement. */
+export declare class ScrollFollow {
+    private following;
+    private readonly threshold;
+    private static readonly owners;
+    private target;
+    private sampledTop;
+    /**
+     * @param following - initial follow intent.
+     * @param threshold - accepted distance from the floor, in pixels.
+     */
+    constructor(following: boolean, threshold: number);
+    /**
+     * Find the mounted controller for reading-position compensation.
+     * @param element - scrollport with an optional follow owner.
+     * @returns its controller, when bound.
+     */
+    static forElement(element: HTMLElement): ScrollFollow | undefined;
+    /**
+     * Share this controller with reading-position compensation for the same scrollport.
+     * @param element - owned scrollport.
+     * @returns release the association on unmount or close.
+     */
+    bind(element: HTMLElement): () => void;
+    /**
+     * Expose follow intent independently of the current offset.
+     * @returns whether content growth should follow the floor.
+     */
+    get active(): boolean;
+    /**
+     * Expose outstanding native motion before accepting reader input.
+     * @returns whether a native follow animation has an outstanding target.
+     */
+    get animating(): boolean;
+    /**
+     * Classify bottom arrivals using this scrollport's own tolerance.
+     * @param metrics - current scroll geometry.
+     * @returns whether the position is within the follow threshold.
+     */
+    nearBottom(metrics: ViewportMetrics): boolean;
+    /**
+     * Commit caller-owned follow decisions without moving the scrollport.
+     * @param active - externally committed follow intent.
+     */
+    setFollowing(active: boolean): void;
+    /** Adopt the next visible layout as a fresh reader position. */
+    reset(): void;
+    /**
+     * Adopt delivered scrolling while retaining intent during native animation.
+     * @param metrics - current geometry.
+     * @param movedByReader - caller attribution; omitted callers compare the last sampled position.
+     * @returns updated follow intent.
+     */
+    sample(metrics: ViewportMetrics, movedByReader?: boolean): boolean;
+    /**
+     * Settle native scrolling; an off-target stop releases follow intent.
+     * @param metrics - actual geometry delivered at scrollend.
+     * @returns follow intent after completing or interrupting native motion.
+     */
+    settle(metrics: ViewportMetrics): boolean;
+    /**
+     * Position immediately and adopt the resulting follow intent.
+     * @param element - scrolling element.
+     * @param metrics - geometry before positioning.
+     * @param top - requested offset, clamped to the measured range.
+     * @returns geometry after positioning.
+     */
+    jump(element: HTMLElement, metrics: ViewportMetrics, top: number): ViewportMetrics;
+    /**
+     * Follow the measured floor, respecting reduced motion for smooth requests.
+     * An outstanding smooth target finishes before another is issued.
+     * Within-tolerance positioning is immediate while no animation is outstanding.
+     * @param element - scrolling element.
+     * @param metrics - current geometry.
+     * @param behavior - native animation for growth, or immediate positioning.
+     * @returns current geometry; smooth requests retain their starting position until native scroll delivery.
+     */
+    toBottom(element: HTMLElement, metrics: ViewportMetrics, behavior: 'instant' | 'smooth'): ViewportMetrics;
+    /**
+     * Cancel native motion before a reader gesture; only subsequent actual movement changes follow intent.
+     * @param element - scrolling element.
+     * @param metrics - position at interruption.
+     */
+    interrupt(element: HTMLElement, metrics: ViewportMetrics): void;
+}
+/**
+ * Retain one independent follow controller without React updates for scroll samples.
+ * @param initial - initial follow intent.
+ * @param threshold - accepted distance from the floor, in pixels.
+ * @returns the stable controller shared by the caller's scroll and resize handlers.
+ */
+export declare function useScrollFollow(initial: boolean, threshold: number): ScrollFollow;
+//# sourceMappingURL=use-scroll-follow.d.ts.map

package/lib/types/client/chat/use-turn-data.d.ts

@@ -0,0 +1,9 @@
+import type { ConversationLocationDataStore, ConversationTurnDataMap } from '@qilin-agent/client-ui-conversation/client';
+/**
+ * Subscribe to one value from a Turn's keyed Location-data store.
+ * @param data - current Turn data store, or absence for a Node outside a Turn.
+ * @param key - declaration-merged business key.
+ * @returns the current value for that key.
+ */
+export declare function useTurnDataValue<Key extends Extract<keyof ConversationTurnDataMap, string>>(data: ConversationLocationDataStore<ConversationTurnDataMap> | undefined, key: Key): Readonly<ConversationTurnDataMap[Key]> | undefined;
+//# sourceMappingURL=use-turn-data.d.ts.map

package/lib/types/client/contract/assistant-content.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantBlock } from '@qilin-agent/client-ui-conversation/client';
+/**
+ * Test whether Assistant blocks contain a user-facing reply rather than only
+ * reasoning or Tool-call protocol material.
+ * @param blocks - Assistant content blocks.
+ * @returns whether the blocks contain visible reply content.
+ */
+export declare function hasAssistantReplyContent(blocks: readonly AssistantBlock[]): boolean;
+//# sourceMappingURL=assistant-content.d.ts.map

package/lib/types/client/contract/chat-nodes.d.ts

@@ -0,0 +1,108 @@
+import type { AssistantBlock, AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationLocation, ConversationViewNode, ModelRetryNode, RunningToolCall, ToolCallBlock } from '@qilin-agent/client-ui-conversation/client';
+/** Final Chat render unit produced by a Chat business Definition. */
+export interface ChatConversationViewNode extends ConversationViewNode {
+    readonly target: 'chat';
+    readonly anchorSeq: number;
+    readonly location: ConversationLocation;
+    readonly visibility: 'visible' | 'hidden';
+}
+/** Merge-extensible payload registry keyed by final Chat renderer kind. */
+export interface ChatNodeDataMap {
+}
+/** Renderer kinds contributed by the currently installed Chat business modules. */
+export type ChatNodeKind = Extract<keyof ChatNodeDataMap, string>;
+/** Final Chat Node narrowed to one registered renderer kind and payload. */
+export type ChatNode<Kind extends ChatNodeKind = ChatNodeKind> = {
+    [RegisteredKind in Kind]: ChatConversationViewNode & {
+        readonly kind: RegisteredKind;
+        readonly data: ChatNodeDataMap[RegisteredKind];
+    };
+}[Kind];
+/** Final Assistant row payload shared by streaming and settled states. */
+export interface AssistantChatData {
+    readonly status: 'running' | 'settled' | 'interrupted';
+    readonly turn: number;
+    readonly step: number;
+    readonly blocks: readonly AssistantBlock[];
+    readonly time: number;
+    readonly usage?: unknown;
+    readonly finalNode?: AssistantMessageNode;
+}
+/** Settled or interrupted Assistant payload with its durable presentation node. */
+export type FinalAssistantChatData = AssistantChatData & {
+    readonly finalNode: AssistantMessageNode;
+};
+/** Root Tool row payload; the root lifecycle owns all recursive subcalls. */
+export interface ToolChatData {
+    readonly root: ToolCallBlock;
+}
+/** One manual command and its correlated compaction transaction. */
+export interface ManualCompactionChatData {
+    readonly command: CommandNode;
+    readonly compaction: CompactionSummaryNode | null;
+}
+/** One durable retry chain rendered as a single row. */
+export interface RetryChatData {
+    readonly attempts: readonly ModelRetryNode[];
+    readonly current: ModelRetryNode;
+}
+/** One provider/model route that contributed a billed request attempt. */
+export interface TurnTokenUsageRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Exact provider-reported token accounting for every attempt in one completed Turn. */
+export interface TurnTokenUsage {
+    /** Sum of uncached prompt input across all attempts. */
+    readonly uncachedInputTokens: number;
+    readonly outputTokens: number;
+    /** Exact aggregate prompt plus output total across all attempts. */
+    readonly totalTokens: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheReadTokens?: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheWriteTokens?: number;
+    /** Output subset, present only when every attempt reported it. */
+    readonly reasoningTokens?: number;
+    /** Present only when every billed attempt has provider/model attribution. */
+    readonly routes?: readonly TurnTokenUsageRoute[];
+}
+/** Turn-local footer row that owns actions and optional feature contributions. */
+export interface TurnTailChatData {
+    readonly turn: number;
+    readonly seq: number;
+    readonly time: number;
+    /** Last finalized content-bearing Assistant in this Turn. */
+    readonly closing: FinalAssistantChatData | null;
+    /** Whether non-rendered later evidence makes the closing seq non-tail. */
+    readonly branchUnavailable: boolean;
+    /** Exact per-Turn accounting; absent when the loaded evidence is incomplete. */
+    readonly tokenUsage?: TurnTokenUsage;
+}
+/** Turn-level process disclosure projected before the finalized answer. */
+export interface TurnProcessChatData {
+    readonly turn: number;
+    readonly controlAnchorSeq: number;
+    readonly processStartSeq: number;
+    readonly answerAnchorSeq: number | null;
+    readonly answerStep: number | null;
+    readonly inlineReasoning: boolean;
+    readonly messageCount: number;
+    readonly toolCallCount: number;
+    readonly subagentCount: number;
+}
+/**
+ * Test whether a Tool root has settled.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root carries its final result.
+ */
+export declare function isSettledTool(block: ToolCallBlock): block is Extract<ToolCallBlock, {
+    kind: 'tool-result';
+}>;
+/**
+ * Test whether a Tool root is still running.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root lacks a final result.
+ */
+export declare function isRunningTool(block: ToolCallBlock): block is RunningToolCall;
+//# sourceMappingURL=chat-nodes.d.ts.map

package/lib/types/client/contract/chat-visibility.d.ts

@@ -0,0 +1,10 @@
+/** Chat-only row visibility; durable events and trajectory inspection remain intact. */
+import type { ChatNode } from './chat-nodes.ts';
+/**
+ * Exclude system prompts, ordinary Context, and permission commands from visible Chat rows.
+ * Context containing tool changes retains its notice row.
+ * @param node - projected Chat node.
+ * @returns whether the node contributes a visible Chat row.
+ */
+export declare function isVisibleChatNode(node: ChatNode): boolean;
+//# sourceMappingURL=chat-visibility.d.ts.map

package/lib/types/client/contract/process-groups.d.ts

@@ -0,0 +1,25 @@
+/** Business data for Chat process groups; source Nodes remain in the Chat store. */
+export type ProcessActivity = 'read' | 'readImage' | 'search' | 'write' | 'edit' | 'commands' | 'code' | 'webSearch' | 'webFetch' | 'subagents' | 'plan' | 'questions' | 'tools';
+/** Distinct-call category ranking and the current live task detail. */
+export interface ProcessActivitySummary {
+    readonly counts: readonly {
+        readonly kind: ProcessActivity;
+        readonly count: number;
+    }[];
+    readonly running: ProcessActivity | undefined;
+    readonly runningDetail: string;
+    /** Present only while the selected live activity has not reached tool/call. */
+    readonly preparing?: true;
+}
+/** Presentation facts for one group between independent replies or input. */
+export interface ProcessGroupData {
+    readonly turn: number;
+    readonly closed: boolean;
+    readonly summary: ProcessActivitySummary;
+}
+declare module '@qilin-agent/client-ui-conversation/client' {
+    interface ConversationGroupDataMap {
+        chat: ProcessGroupData;
+    }
+}
+//# sourceMappingURL=process-groups.d.ts.map